Add String.localeCompare options (#8287)

* Add String.localeCompare options

* CHANGELOG

Author: cknitt

CHANGELOG.md

@@ -19,6 +19,7 @@
 #### :rocket: New Feature
 
 - Reanalyze: add glob pattern support for suppress/unsuppress configurations (e.g., `"src/generated/**"`). https://github.com/rescript-lang/rescript/pull/8277
+- Add optional `~locales` and `~options` parameters to `String.localeCompare`. https://github.com/rescript-lang/rescript/pull/8287
 
 #### :bug: Bug fix
 

packages/@rescript/runtime/Stdlib_String.res

@@ -182,7 +182,13 @@ external substringToEnd: (string, ~start: int) => string = "substring"
 @send external padStart: (string, int, string) => string = "padStart"
 @send external padEnd: (string, int, string) => string = "padEnd"
 
-@send external localeCompare: (string, string) => float = "localeCompare"
+@send
+external localeCompare: (
+  string,
+  string,
+  ~locales: array<string>=?,
+  ~options: Stdlib_Intl_Collator.options=?,
+) => float = "localeCompare"
 
 let isEmpty = s => length(s) == 0
 

packages/@rescript/runtime/Stdlib_String.resi

@@ -1174,22 +1174,32 @@ String.padEnd("abc", 1, "") == "abc"
 external padEnd: (string, int, string) => string = "padEnd"
 
 /**
-`localeCompare(referenceStr, compareStr)` returns a float than indicatings
+`localeCompare(referenceStr, compareStr, ~locales=?, ~options=?)` returns a float indicating
 whether a reference string comes before or after, or is the same as the given
-string in sort order. If `referenceStr` occurs before `compareStr` positive if
-the `referenceStr` occurs after `compareStr`, `0` if they are equivalent.
-Do not rely on exact return values of `-1` or `1`
+string in sort order. Returns a negative value if `referenceStr` occurs before `compareStr`,
+positive if `referenceStr` occurs after `compareStr`, `0` if they are equivalent.
+Do not rely on exact return values of `-1` or `1`.
+
+Optionally takes `~locales` to specify locale(s) and `~options` to customize comparison behavior
+(e.g., sensitivity, case ordering, numeric sorting). These correspond to the `Intl.Collator` options.
 See [`String.localeCompare`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/localeCompare) on MDN.
 
 ## Examples
 
 ```rescript
 String.localeCompare("a", "c") < 0.0 == true
 String.localeCompare("a", "a") == 0.0
+String.localeCompare("a", "b", ~locales=["en-US"]) < 0.0 == true
+String.localeCompare("a", "A", ~locales=["en-US"], ~options={sensitivity: #base}) == 0.0
 ```
 */
 @send
-external localeCompare: (string, string) => float = "localeCompare"
+external localeCompare: (
+  string,
+  string,
+  ~locales: array<string>=?,
+  ~options: Stdlib_Intl_Collator.options=?,
+) => float = "localeCompare"
 
 /**
   `ignore(string)` ignores the provided string and returns unit.