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

package/models/models/kos-log-manager/kos-log-manager-model.d.ts

@@ -10,23 +10,68 @@ import { KosRequest, KosResponse } from '../../../core';
  */
 export declare const MODEL_TYPE = "kos-log-manager-model";
 /**
- * Public interface for the KOS Log Manager Model.
- * Provides runtime log level management capabilities for the KOS UI SDK.
- */
-export type KosLogManagerModel = PublicModelInterface<KosLogManagerModelImpl>;
-/**
- * Implementation of the KOS Log Manager Model.
+ * KOS Log Manager Model - Centralized runtime log level management for the entire KOS system.
+ *
+ * This singleton model provides comprehensive control over logging behavior across the KOS UI SDK
+ * and connected applications. It manages dynamic log level overrides, responds to real-time
+ * configuration changes, and provides both REST API and WebSocket interfaces for log management.
+ * Essential for debugging, performance monitoring, and production troubleshooting.
+ *
+ * ## Key Features
+ * - **Runtime Log Level Control** - Dynamically adjust log levels without application restart
+ * - **Hierarchical Logger Management** - Apply overrides to parent loggers and all children
+ * - **Real-time Configuration** - WebSocket-based updates propagate instantly across clients
+ * - **REST API Integration** - Query and manage logger configurations via HTTP endpoints
+ * - **Override Persistence** - Log overrides are maintained across sessions and page refreshes
+ * - **Multi-Node Support** - Coordinate logging across different KOS device nodes
+ *
+ * ## Topic-Based Reactivity
+ * The model listens to these KOS topics for real-time log management:
+ * - **`/kos/logs/override/add/*`** - Fired when new log level overrides are created
+ * - **`/kos/logs/override/remove/*`** - Fired when log level overrides are removed
+ *
+ * Both topics support wildcard capture for node type targeting, enabling precise
+ * control over which device nodes receive logging configuration changes.
  *
- * This model manages log levels for different loggers in the KOS system,
- * allowing dynamic runtime configuration of logging verbosity.
+ * ## Architecture Integration
+ * The log manager integrates with the broader KOS logging ecosystem:
+ * - **KosLog System** - Manages underlying logger instances and level settings
+ * - **LogStreamModel** - Streams managed by this model's log level policies
+ * - **LogBlockModel** - Individual log entries governed by level settings
+ * - **REST Endpoints** - Provides `/api/kos/ui/loggers` for external access
  *
- * Key features:
- * - Maintains a collection of log level overrides
- * - Responds to WebSocket events for adding/removing log overrides
- * - Provides REST API endpoint for retrieving all logger configurations
- * - Automatically applies log level changes to matching loggers
+ * ## Common Use Cases
+ * - **Development Debugging** - Increase log verbosity for specific components during development
+ * - **Production Troubleshooting** - Temporarily enable debug logging to diagnose issues
+ * - **Performance Monitoring** - Adjust log levels to reduce overhead in production
+ * - **System Administration** - Centrally manage logging across distributed KOS deployments
+ * - **Dynamic Configuration** - Change logging behavior without service interruption
+ * - **Selective Logging** - Enable detailed logging for specific modules while keeping others quiet
  *
- * @kosModel Decorated as a KOS model with type 'kos-log-manager-model'
+ * @interface
+ * @example Basic Usage
+ * ```typescript
+ * const logManager = KosLogManager.instance('log-control').build();
+ *
+ * // Get all current logger configurations via REST API
+ * const loggers = await logManager.getAllLoggers();
+ * console.log(`Managing ${loggers.length} loggers`);
+ * ```
+ *
+ * @group KOS Model
+ * @category Device Logging
+ * @useDeclaredType
+ *
+ * @see {@link LogStreamModel} - Streams whose content is governed by log levels managed here
+ * @see {@link LogBlockModel} - Individual log entries affected by level settings
+ * @see {@link KosLogManagerOptions} - Configuration options for the log manager
+ * @see {@link LogOverride} - Log level override structure for runtime control
+ * @see {@link LogLevelDescriptor} - Logger information structure returned by REST API
+ */
+export type KosLogManagerModel = PublicModelInterface<KosLogManagerModelImpl>;
+/**
+ * @ignore
+ * @internal
  */
 export declare class KosLogManagerModelImpl implements IKosDataModel, IKosIdentifiable {
     id: string;
@@ -80,12 +125,14 @@ export declare class KosLogManagerModelImpl implements IKosDataModel, IKosIdenti
     /**
      * Initializes the log manager model.
      * Called during model creation lifecycle.
+     * @internal
      */
     init(): Promise<void>;
     /**
      * Loads existing log overrides from the server.
      * Fetches UI-specific overrides and applies them to the current loggers.
      * Called after model initialization.
+     * @internal
      */
     load(): Promise<void>;
 }

package/models/models/kos-log-manager/kos-log-manager-model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"kos-log-manager-model.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/kos-log-manager/kos-log-manager-model.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,KAAK,UAAU,EACf,KAAK,WAAW,EACjB,MAAM,eAAe,CAAC;AACvB,OAAO,EAIL,KAAK,uBAAuB,EAC7B,MAAM,+BAA+B,CAAC;AACvC,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,EACV,oBAAoB,EACpB,kBAAkB,EAElB,WAAW,EACZ,MAAM,SAAS,CAAC;AAEjB;;GAEG;AACH,eAAO,MAAM,UAAU,0BAA0B,CAAC;AAElD;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG,oBAAoB,CAAC,sBAAsB,CAAC,CAAC;AA0B9E;;;;;;;;;;;;;GAaG;AACH,qBACa,sBAAuB,YAAW,aAAa,EAAE,gBAAgB;IAC5E,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,CAAC,MAAM,CAAmB;IAEjC,OAAO,CAAC,UAAU,CAAiC;gBAEjD,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,oBAAoB,EAC7B,OAAO,EAAE,kBAAkB;IAU7B,WAAW,CAAC,QAAQ,EAAE,oBAAoB,GAAG,IAAI;IAMjD;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAmBtB;;;;;;OAMG;IAEG,aAAa,CACjB,IAAI,CAAC,EAAE,UAAU,EACjB,GAAG,CAAC,EAAE,WAAW,GAChB,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAOhC;;;;;;OAMG;IACH,OAAO,CAAC,YAAY;IAwBpB;;;;;;OAMG;IACH,OAAO,CAAC,cAAc;IAsBtB;;;;;OAKG;IAMH,mBAAmB,CACjB,QAAQ,EAAE,WAAW,EACrB,OAAO,EAAE,uBAAuB,CAAC,GAAG,CAAC;IAWvC;;;;OAIG;IAMH,qBAAqB,CAAC,QAAQ,EAAE,WAAW;IAK3C;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B;;;;OAIG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAsB5B"}
+{"version":3,"file":"kos-log-manager-model.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/kos-log-manager/kos-log-manager-model.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,KAAK,UAAU,EACf,KAAK,WAAW,EACjB,MAAM,eAAe,CAAC;AACvB,OAAO,EAIL,KAAK,uBAAuB,EAC7B,MAAM,+BAA+B,CAAC;AACvC,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,EACV,oBAAoB,EACpB,kBAAkB,EAElB,WAAW,EACZ,MAAM,SAAS,CAAC;AAEjB;;GAEG;AACH,eAAO,MAAM,UAAU,0BAA0B,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,MAAM,MAAM,kBAAkB,GAAG,oBAAoB,CAAC,sBAAsB,CAAC,CAAC;AA2B9E;;;GAGG;AACH,qBACa,sBAAuB,YAAW,aAAa,EAAE,gBAAgB;IAC5E,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,CAAC,MAAM,CAAmB;IAEjC,OAAO,CAAC,UAAU,CAAiC;gBAEjD,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,oBAAoB,EAC7B,OAAO,EAAE,kBAAkB;IAU7B,WAAW,CAAC,QAAQ,EAAE,oBAAoB,GAAG,IAAI;IAMjD;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAqBtB;;;;;;OAMG;IAEG,aAAa,CACjB,IAAI,CAAC,EAAE,UAAU,EACjB,GAAG,CAAC,EAAE,WAAW,GAChB,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAOhC;;;;;;OAMG;IACH,OAAO,CAAC,YAAY;IAwBpB;;;;;;OAMG;IACH,OAAO,CAAC,cAAc;IAsBtB;;;;;OAKG;IAMH,mBAAmB,CACjB,QAAQ,EAAE,WAAW,EACrB,OAAO,EAAE,uBAAuB,CAAC,GAAG,CAAC;IAWvC;;;;OAIG;IAMH,qBAAqB,CAAC,QAAQ,EAAE,WAAW;IAK3C;;;;OAIG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B;;;;;OAKG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAwB5B"}

package/models/models/kos-log-manager/types/index.d.ts

@@ -1,14 +1,201 @@
+/**
+ * Configuration options for KosLogManager model instances.
+ *
+ * Currently an empty interface but reserved for future log management
+ * configuration options such as default log levels, override policies,
+ * or persistence settings.
+ *
+ * @example Basic Log Manager Configuration
+ * ```typescript
+ * const options: KosLogManagerOptions = {
+ *   // Future options will be added here
+ * };
+ *
+ * const logManager = KosLogManager.instance('log-control')
+ *   .options(options)
+ *   .build();
+ * ```
+ *
+ * @group KOS Model
+ * @category Device Logging
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
 export interface KosLogManagerOptions {}
 
+/**
+ * Standard log level names supported by the KOS logging system.
+ *
+ * These correspond to common logging levels with increasing severity:
+ * - trace: Most verbose, includes all debug information
+ * - debug: Detailed information for debugging
+ * - info: General information messages (default)
+ * - warn: Warning messages about potential issues
+ * - error: Error messages for serious problems
+ *
+ * @example Log Level Usage
+ * ```typescript
+ * const levels: LogLevelNames[] = ['trace', 'debug', 'info', 'warn', 'error'];
+ *
+ * // Set different levels for different components
+ * const productionLevel: LogLevelNames = 'warn';
+ * const developmentLevel: LogLevelNames = 'debug';
+ * const troubleshootingLevel: LogLevelNames = 'trace';
+ * ```
+ *
+ * @group KOS Model
+ * @category Device Logging
+ */
 export type LogLevelNames = "trace" | "debug" | "info" | "warn" | "error";
+
+/**
+ * Log level override configuration for runtime log management.
+ *
+ * Used to dynamically change log levels for specific loggers or logger hierarchies
+ * without requiring application restart. Overrides are applied to the target logger
+ * and all child loggers whose names start with the override name.
+ *
+ * @example Creating Log Overrides
+ * ```typescript
+ * // Enable debug logging for all models
+ * const modelDebugOverride: LogOverride = {
+ *   name: 'kos-ui-sdk.models',
+ *   level: 'debug',
+ *   type: 'UI',
+ *   id: 'models-debug'
+ * };
+ *
+ * // Enable error-only logging for performance
+ * const performanceOverride: LogOverride = {
+ *   name: 'kos-ui-sdk.services.heavy-computation',
+ *   level: 'error',
+ *   type: 'UI',
+ *   id: 'perf-override'
+ * };
+ *
+ * // Troubleshooting override for specific component
+ * const troubleshootOverride: LogOverride = {
+ *   name: 'kos-ui-sdk.models.log-stream',
+ *   level: 'trace',
+ *   type: 'UI',
+ *   id: 'log-stream-debug'
+ * };
+ * ```
+ *
+ * @example Hierarchical Override Effects
+ * ```typescript
+ * // Setting 'kos-ui-sdk' affects all child loggers:
+ * const rootOverride: LogOverride = {
+ *   name: 'kos-ui-sdk',
+ *   level: 'debug',
+ *   type: 'UI',
+ *   id: 'sdk-debug'
+ * };
+ *
+ * // This affects:
+ * // - kos-ui-sdk.models.log-stream
+ * // - kos-ui-sdk.models.log-block
+ * // - kos-ui-sdk.services.api
+ * // - kos-ui-sdk.core.events
+ * // ... and all other loggers starting with 'kos-ui-sdk'
+ * ```
+ *
+ * @group KOS Model
+ * @category Device Logging
+ */
 export interface LogOverride {
+  /**
+   * Target log level to apply to the logger and its children.
+   *
+   * All loggers whose names start with the 'name' property will
+   * be set to this level until the override is removed.
+   */
   level: LogLevelNames;
+
+  /**
+   * Logger name or prefix to target for the override.
+   *
+   * The override applies to this exact logger name and all loggers
+   * whose names start with this string. Use hierarchical naming
+   * like 'kos-ui-sdk.models' to target groups of related loggers.
+   */
   name: string;
+
+  /**
+   * Type of override, typically 'UI' for KOS UI SDK overrides.
+   *
+   * Used to categorize and filter overrides by their source or purpose.
+   * Different types can be managed separately.
+   */
   type: string;
+
+  /**
+   * Unique identifier for this override.
+   *
+   * Used to track and remove specific overrides. Should be unique
+   * within the system to prevent conflicts.
+   */
   id: string;
 }
 
+/**
+ * Logger information descriptor returned by the log manager REST API.
+ *
+ * Provides the current state of a logger including its name and active log level.
+ * Used for querying logger configurations and displaying current system state.
+ *
+ * @example Processing Logger Descriptors
+ * ```typescript
+ * // Get all loggers from the API
+ * const loggers: LogLevelDescriptor[] = await logManager.getAllLoggers();
+ *
+ * // Analyze logging configuration
+ * const debugLoggers = loggers.filter(l => l.level === 'debug');
+ * const errorOnlyLoggers = loggers.filter(l => l.level === 'error');
+ *
+ * console.log(`${debugLoggers.length} loggers in debug mode`);
+ * console.log(`${errorOnlyLoggers.length} loggers showing errors only`);
+ *
+ * // Find specific logger
+ * const streamLogger = loggers.find(l => l.name.includes('log-stream'));
+ * if (streamLogger) {
+ *   console.log(`Log stream logger level: ${streamLogger.level}`);
+ * }
+ * ```
+ *
+ * @example Building Logger Management UI
+ * ```typescript
+ * // Use descriptors to build management interfaces
+ * const LoggerList: React.FC<{ loggers: LogLevelDescriptor[] }> = ({ loggers }) => (
+ *   <div className="logger-list">
+ *     {loggers.map(logger => (
+ *       <div key={logger.name} className="logger-item">
+ *         <span className="logger-name">{logger.name}</span>
+ *         <span className={`logger-level level-${logger.level}`}>
+ *           {logger.level.toUpperCase()}
+ *         </span>
+ *       </div>
+ *     ))}
+ *   </div>
+ * );
+ * ```
+ *
+ * @group KOS Model
+ * @category Device Logging
+ */
 export interface LogLevelDescriptor {
+  /**
+   * Full name of the logger.
+   *
+   * Typically follows hierarchical naming conventions like
+   * 'kos-ui-sdk.models.log-stream' or 'kos-ui-sdk.services.api'.
+   */
   name: string;
+
+  /**
+   * Current active log level for this logger.
+   *
+   * Shows the effective level after all overrides have been applied.
+   * This is the level that determines which log messages are actually output.
+   */
   level: LogLevelNames;
 }

package/models/models/kos-time/kos-time-model.d.ts

@@ -2,7 +2,65 @@ import { DateBean, KosTimeOptions, TimeBean } from './types';
 import { IKosDataModel, IKosModelLogger, KosContextLogger, KosCreationContext, PublicModelInterface } from '../../../core';
 
 export declare const MODEL_TYPE = "kos-time-model";
+/**
+ * KOS Time Model - System time management with real-time synchronization and timezone control.
+ *
+ * This singleton model provides centralized control over system time, date, and timezone settings
+ * with automatic event propagation when changes occur. Essential for applications that need to
+ * synchronize time-based operations, schedule events, or maintain consistent timestamps across
+ * the system.
+ *
+ * ## Key Features
+ * - **System Time Control** - Update system hours, minutes, and seconds programmatically
+ * - **Date Management** - Set system date including month, day, and year
+ * - **Timezone Handling** - Change and track timezone with automatic updates
+ * - **Real-time Events** - Automatic notifications when time, date, or timezone changes
+ * - **EventBus Integration** - Publishes changes to internal EventBus for UI updates
+ * - **WebSocket Sync** - Changes propagate across all connected clients
+ *
+ * ## Topic-Based Reactivity
+ * The model listens to three KOS topics for time synchronization:
+ * - **`/kos/time/time`** - Fired when system time changes (hour/minute/second)
+ * - **`/kos/time/day`** - Fired when the date changes (day rollover or manual change)
+ * - **`/kos/time/timezone`** - Fired when timezone is updated
+ *
+ * Additionally, the model publishes to internal EventBus topics:
+ * - `TIME_CHANGE` - For UI components to react to time updates
+ * - `DAY_CHANGE` - For date-dependent UI updates
+ * - `TIMEZONE_CHANGE` - For timezone-aware components
+ *
+ * ## Common Use Cases
+ * - **System Clock Management** - Synchronize device time with server time
+ * - **Scheduled Operations** - Trigger events based on time changes
+ * - **Multi-timezone Support** - Handle devices in different time zones
+ * - **Time-based UI Updates** - Keep clocks and calendars synchronized
+ * - **Audit Logging** - Ensure consistent timestamps across the system
+ * - **Day Rollover Handling** - Reset daily counters or refresh data
+ *
+ * @interface
+ * @example Basic Usage
+ * ```typescript
+ * const timeModel = KosTime.instance().build();
+ *
+ * // Update system time and date
+ * await timeModel.updateSystemTime({ hour: 15, min: 45, sec: 30 });
+ * await timeModel.updateSystemDate({ month: 3, day: 15, year: 2024 });
+ * await timeModel.updateSystemTimezone('America/New_York');
+ * ```
+ *
+ * @group KOS Model
+ * @category System Integration
+ * @useDeclaredType
+ *
+ * @see {@link TimeBean} - Time value structure (hour, minute, second)
+ * @see {@link DateBean} - Date value structure (month, day, year)
+ * @see {@link KosTimeOptions} - Configuration options for time model
+ */
 export type KosTimeModel = PublicModelInterface<KosTimeModelImpl>;
+/**
+ * @ignore
+ * @internal
+ */
 export declare class KosTimeModelImpl implements IKosModelLogger, IKosDataModel {
     id: string;
     logger: KosContextLogger;
@@ -28,9 +86,15 @@ export declare class KosTimeModelImpl implements IKosModelLogger, IKosDataModel
     handleTimeChange(): void;
     handleDayChange(): void;
     handleTimeZoneChange(): Promise<void>;
+    /**
+     * @internal
+     */
     init(): Promise<void>;
     private retrieveTimezone;
     setTimezone(tz: string): void;
+    /**
+     * @internal
+     */
     load(): Promise<void>;
 }
 //# sourceMappingURL=kos-time-model.d.ts.map

package/models/models/kos-time/kos-time-model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"kos-time-model.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/kos-time/kos-time-model.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,aAAa,EACb,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,EACrB,MAAM,eAAe,CAAC;AAIvB,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,cAAc,EAAE,KAAK,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC5E,eAAO,MAAM,UAAU,mBAAmB,CAAC;AAM3C,MAAM,MAAM,YAAY,GAAG,oBAAoB,CAAC,gBAAgB,CAAC,CAAC;AAClE,qBACa,gBAAiB,YAAW,eAAe,EAAE,aAAa;IACrE,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,gBAAgB,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;gBAEf,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,cAAc,EACxB,OAAO,EAAE,kBAAkB;IAO7B;;;;OAIG;IACG,gBAAgB,CAAC,IAAI,EAAE,QAAQ;IAIrC;;;;OAIG;IACG,gBAAgB,CAAC,IAAI,EAAE,QAAQ;IAIrC;;;OAGG;IACG,oBAAoB,CAAC,QAAQ,EAAE,MAAM;IAK3C,gBAAgB,IAAI,IAAI;IAMxB,eAAe,IAAI,IAAI;IAMjB,oBAAoB;IAQpB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;YAIb,gBAAgB;IAI9B,WAAW,CAAC,EAAE,EAAE,MAAM;IAGhB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAI5B"}
+{"version":3,"file":"kos-time-model.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/kos-time/kos-time-model.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,aAAa,EACb,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,EACrB,MAAM,eAAe,CAAC;AAIvB,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,cAAc,EAAE,KAAK,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC5E,eAAO,MAAM,UAAU,mBAAmB,CAAC;AAM3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,MAAM,MAAM,YAAY,GAAG,oBAAoB,CAAC,gBAAgB,CAAC,CAAC;AAElE;;;GAGG;AACH,qBACa,gBAAiB,YAAW,eAAe,EAAE,aAAa;IACrE,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,gBAAgB,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;gBAEf,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,cAAc,EACxB,OAAO,EAAE,kBAAkB;IAO7B;;;;OAIG;IACG,gBAAgB,CAAC,IAAI,EAAE,QAAQ;IAIrC;;;;OAIG;IACG,gBAAgB,CAAC,IAAI,EAAE,QAAQ;IAIrC;;;OAGG;IACG,oBAAoB,CAAC,QAAQ,EAAE,MAAM;IAK3C,gBAAgB,IAAI,IAAI;IAMxB,eAAe,IAAI,IAAI;IAMjB,oBAAoB;IAQ1B;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;YAIb,gBAAgB;IAI9B,WAAW,CAAC,EAAE,EAAE,MAAM;IAItB;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAI5B"}

package/models/models/kos-time/types/index.d.ts

@@ -1,13 +1,93 @@
+/**
+ * Time value structure for system time operations.
+ *
+ * Represents a specific time of day with hour, minute, and second components.
+ * Used when updating system time through the KosTime model.
+ *
+ * @example
+ * ```typescript
+ * const morningTime: TimeBean = {
+ *   hour: 9,    // 9 AM (24-hour format)
+ *   min: 30,    // 30 minutes
+ *   sec: 0      // 0 seconds
+ * };
+ *
+ * const afternoonTime: TimeBean = {
+ *   hour: 15,   // 3 PM (24-hour format)
+ *   min: 45,
+ *   sec: 30
+ * };
+ *
+ * await timeModel.updateSystemTime(morningTime);
+ * ```
+ *
+ * @category System Integration
+ * @category Time Management
+ */
 export interface TimeBean {
+  /** Hour in 24-hour format (0-23) */
   hour: number;
+  /** Minutes (0-59) */
   min: number;
+  /** Seconds (0-59) */
   sec: number;
 }
 
+/**
+ * Date value structure for system date operations.
+ *
+ * Represents a specific calendar date with month, day, and year components.
+ * Used when updating system date through the KosTime model.
+ *
+ * @example
+ * ```typescript
+ * const newYear: DateBean = {
+ *   month: 1,   // January
+ *   day: 1,     // 1st
+ *   year: 2024  // 2024
+ * };
+ *
+ * const independence: DateBean = {
+ *   month: 7,   // July
+ *   day: 4,     // 4th
+ *   year: 2024
+ * };
+ *
+ * await timeModel.updateSystemDate(newYear);
+ * ```
+ *
+ * @category System Integration
+ * @category Time Management
+ */
 export interface DateBean {
+  /** Month (1-12, where 1 = January, 12 = December) */
   month: number;
+  /** Day of the month (1-31, depending on month) */
   day: number;
+  /** Full year (e.g., 2024) */
   year: number;
 }
 
+/**
+ * Configuration options for KosTime model instances.
+ *
+ * Currently an empty interface but reserved for future time-related
+ * configuration options such as default timezone, time format preferences,
+ * or synchronization settings.
+ *
+ * @example
+ * ```typescript
+ * const options: KosTimeOptions = {
+ *   // Future options will be added here
+ * };
+ *
+ * const timeModel = KosTime.instance()
+ *   .options(options)
+ *   .build();
+ * ```
+ *
+ * @category Model Configuration
+ * @category System Integration
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
 export interface KosTimeOptions {}

package/models/models/log-block/log-block-container-model.d.ts

@@ -6,7 +6,139 @@ import { IKosDataModel, KosCreationContext } from '../../../core/core/kosModel';
 import { IKosModelContainer } from '../../../core/core/kos-container-model';
 
 export declare const MODEL_TYPE = "log-block-container-model";
+/**
+ * Log Block Container Model - Manages multiple log blocks with automatic sorting and organization.
+ *
+ * This container model manages collections of LogBlockModel instances, providing organized access
+ * to log blocks with automatic sorting by block number. It serves as the storage layer within
+ * LogStreamModel instances, handling the efficient organization and retrieval of log blocks
+ * that make up a complete log stream.
+ *
+ * ## Key Features
+ * - **Automatic Sorting** - Maintains blocks sorted by block number for sequential access
+ * - **Block Management** - Add, remove, and retrieve log blocks efficiently
+ * - **Memory Organization** - Organized storage of log blocks within streams
+ * - **Stream Integration** - Essential component of LogStreamModel architecture
+ * - **Sequential Access** - Optimized for accessing blocks in chronological order
+ *
+ * ## Architecture Role
+ * The container fits into the log streaming architecture as:
+ * - **LogStreamModel** uses LogBlockContainerModel to organize its blocks
+ * - **LogBlockContainerModel** manages multiple LogBlockModel instances
+ * - **LogBlockModel** contains the actual log lines and metadata
+ * - Automatic sorting by blockNum ensures proper sequential log ordering
+ *
+ * ## Common Use Cases
+ * - **Stream Block Storage** - Central storage for all blocks within a log stream
+ * - **Sequential Block Access** - Navigate through log blocks in chronological order
+ * - **Block Organization** - Maintain sorted collections of log segments
+ * - **Memory Management** - Efficiently organize log data for stream processing
+ * - **Block Lifecycle** - Handle adding and removing blocks as streams evolve
+ *
+ * @example Container Usage Within Stream
+ * ```typescript
+ * // Typically used internally by LogStreamModel
+ * const logStream = LogStream.instance('system-logs').build();
+ * await logStream.load();
+ *
+ * // Access the container through the stream
+ * const blockContainer = logStream._blocks; // Internal container
+ * const blocks = logStream.blocks; // Public access to blocks
+ *
+ * // Container automatically sorts blocks by blockNum
+ * console.log(`Stream has ${blocks.length} blocks`);
+ * blocks.forEach(block => {
+ *   console.log(`Block ${block.blockNum}: ${block.lineCount} lines`);
+ * });
+ * ```
+ *
+ * @example Direct Container Operations
+ * ```typescript
+ * // Create container (typically done internally)
+ * const container = LogBlockContainer.instance('log-blocks')
+ *   .options({})
+ *   .build();
+ *
+ * // Add blocks to container
+ * const block1 = LogBlock.instance('block-1')
+ *   .options({
+ *     nodeId: 'primary',
+ *     stream: 'app-logs',
+ *     blockNum: 1,
+ *     startLineNum: 1,
+ *     endLineNum: 100,
+ *     startTime: new Date('2024-01-01T10:00:00Z'),
+ *     endTime: new Date('2024-01-01T10:05:00Z'),
+ *     lineCount: 100
+ *   })
+ *   .build();
+ *
+ * const block2 = LogBlock.instance('block-2')
+ *   .options({
+ *     nodeId: 'primary',
+ *     stream: 'app-logs',
+ *     blockNum: 2,
+ *     startLineNum: 101,
+ *     endLineNum: 200,
+ *     startTime: new Date('2024-01-01T10:05:00Z'),
+ *     endTime: new Date('2024-01-01T10:10:00Z'),
+ *     lineCount: 100
+ *   })
+ *   .build();
+ *
+ * container.addModel(block1);
+ * container.addModel(block2);
+ *
+ * // Blocks are automatically sorted by blockNum
+ * const sortedBlocks = container.data;
+ * console.log(`First block: ${sortedBlocks[0].blockNum}`); // 1
+ * console.log(`Second block: ${sortedBlocks[1].blockNum}`); // 2
+ * ```
+ *
+ * @example React Block List Component
+ * ```typescript
+ * const BlockList: React.FC<{ container: LogBlockContainerModel }> = kosComponent(({ container }) => {
+ *   return (
+ *     <div className="block-list">
+ *       <h3>Log Blocks ({container.data.length})</h3>
+ *       <div className="blocks">
+ *         {container.data.map(block => (
+ *           <div key={block.id} className="block-item">
+ *             <div className="block-header">
+ *               <span className="block-num">Block {block.blockNum}</span>
+ *               <span className="line-range">
+ *                 Lines {block.startLineNum}-{block.endLineNum}
+ *               </span>
+ *             </div>
+ *             <div className="block-details">
+ *               <span>Stream: {block.stream}</span>
+ *               <span>Lines: {block.lineCount}</span>
+ *               <span>Loaded: {block.lines.length}</span>
+ *             </div>
+ *             <div className="block-time">
+ *               {block.startTime.toLocaleString()} - {block.endTime.toLocaleString()}
+ *             </div>
+ *           </div>
+ *         ))}
+ *       </div>
+ *     </div>
+ *   );
+ * });
+ * ```
+ *
+ * @group KOS Model
+ * @category Device Logging
+ * @interface
+ *
+ * @see {@link LogStreamModel} - Parent stream model that uses this container
+ * @see {@link LogBlockModel} - Individual log blocks managed by this container
+ * @see {@link LogBlockContainerOptions} - Configuration options for the container
+ */
 export type LogBlockContainerModel = PublicModelInterface<LogBlockContainerModelImpl>;
+/**
+ * @ignore
+ * @internal
+ */
 export declare class LogBlockContainerModelImpl implements IKosIdentifiable, IKosModelHolder<LogBlockModel>, IKosDataModel {
     id: string;
     private logger;

package/models/models/log-block/log-block-container-model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"log-block-container-model.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/log-block/log-block-container-model.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,wCAAwC,CAAC;AAChD,OAAO,KAAK,EACV,aAAa,EAEb,kBAAkB,EACnB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EACV,eAAe,EACf,oBAAoB,EACrB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,SAAS,CAAC;AAExD,eAAO,MAAM,UAAU,8BAA8B,CAAC;AAEtD,MAAM,MAAM,sBAAsB,GAChC,oBAAoB,CAAC,0BAA0B,CAAC,CAAC;AAEnD,qBACa,0BACX,YAAW,gBAAgB,EAAE,eAAe,CAAC,aAAa,CAAC,EAAE,aAAa;IAE1E,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,CAAC,MAAM,CAAmB;IACvB,OAAO,CAAC,OAAO,CAAoC;gBAE3D,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,wBAAwB,EACjC,OAAO,EAAE,kBAAkB;IAa7B,QAAQ,CAAC,EAAE,EAAE,MAAM;IAGnB,IAAI,MAAM,sCAET;IACD,IAAI,IAAI,oBAEP;IAED,QAAQ,CAAC,KAAK,EAAE,aAAa;IAI7B,WAAW,CAAC,EAAE,EAAE,MAAM;IAKhB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAIrB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAG5B"}
+{"version":3,"file":"log-block-container-model.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/log-block/log-block-container-model.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,wCAAwC,CAAC;AAChD,OAAO,KAAK,EACV,aAAa,EAEb,kBAAkB,EACnB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EACV,eAAe,EACf,oBAAoB,EACrB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,SAAS,CAAC;AAExD,eAAO,MAAM,UAAU,8BAA8B,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+HG;AACH,MAAM,MAAM,sBAAsB,GAChC,oBAAoB,CAAC,0BAA0B,CAAC,CAAC;AAEnD;;;GAGG;AACH,qBACa,0BACX,YAAW,gBAAgB,EAAE,eAAe,CAAC,aAAa,CAAC,EAAE,aAAa;IAE1E,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,CAAC,MAAM,CAAmB;IACvB,OAAO,CAAC,OAAO,CAAoC;gBAE3D,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,wBAAwB,EACjC,OAAO,EAAE,kBAAkB;IAa7B,QAAQ,CAAC,EAAE,EAAE,MAAM;IAGnB,IAAI,MAAM,sCAET;IACD,IAAI,IAAI,oBAEP;IAED,QAAQ,CAAC,KAAK,EAAE,aAAa;IAI7B,WAAW,CAAC,EAAE,EAAE,MAAM;IAKhB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAIrB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAG5B"}