refactor(shared): update utilities, API layer, and types

src/shared/lib/utils/clampNumber/clampNumber.ts

@@ -1,9 +1,20 @@
 /**
- * Clamp a number within a range.
- * @param value The number to clamp.
- * @param min minimum value
- * @param max maximum value
- * @returns The clamped number.
+ * Clamps a number within a specified range
+ *
+ * Ensures a value falls between minimum and maximum bounds.
+ * Values below min return min, values above max return max.
+ *
+ * @param value - The number to clamp
+ * @param min - Minimum allowed value (inclusive)
+ * @param max - Maximum allowed value (inclusive)
+ * @returns The clamped number
+ *
+ * @example
+ * ```ts
+ * clampNumber(5, 0, 10); // 5
+ * clampNumber(-5, 0, 10); // 0
+ * clampNumber(15, 0, 10); // 10
+ * ```
  */
 export function clampNumber(value: number, min: number, max: number): number {
     return Math.min(Math.max(value, min), max);