From ce6d9e26cdda2718c4e830cd75fbe55bf94cf58e Mon Sep 17 00:00:00 2001
From: Juho Teperi <juho.teperi@iki.fi>
Date: Wed, 22 Jan 2025 14:35:56 +0200
Subject: [PATCH] Update docstrings and changelog

---
 CHANGELOG.md                                  |  6 ++++
 .../src/reitit/frontend/easy.cljs             | 35 +++++++++++--------
 2 files changed, 27 insertions(+), 14 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2c6a455c6..66809b529 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -15,6 +15,12 @@ We use [Break Versioning][breakver]. The version numbers follow a `<major>.<mino
 ## UNRELEASED
 
 * Improve OpenAPI docs, plus don't emit `:description` in the wrong place [#702](https://github.com/metosin/reitit/pull/702)
+* *POTENTIALLY BREAKING* The frontend functions (href, push/replace-state, set-query) now
+  encode query-string values using configured coercion when possible (only Malli supports encoding).
+    - You can use this to encode query parameter values before they are URL-encoded. This works for DateTimes, collections etc.
+    - In most cases this shouldn't break existing uses, but it is possible even without
+      a custom encoding function, the default Malli string-transformer could encode some values differently
+      then previously.
 
 ## 0.7.2 (2024-09-02)
 
diff --git a/modules/reitit-frontend/src/reitit/frontend/easy.cljs b/modules/reitit-frontend/src/reitit/frontend/easy.cljs
index b50bbb48a..c68781947 100644
--- a/modules/reitit-frontend/src/reitit/frontend/easy.cljs
+++ b/modules/reitit-frontend/src/reitit/frontend/easy.cljs
@@ -48,9 +48,10 @@
   The URL is formatted using Reitit frontend history handler, so using it with
   anchor element href will correctly trigger route change event.
 
-  Note: currently collections in query-parameters are encoded as field-value
-  pairs separated by &, i.e. \"?a=1&a=2\", if you want to encode them
-  differently, convert the collections to strings first."
+  By default currently collections in query parameters are encoded as field-value
+  pairs separated by &, i.e. \"?a=1&a=2\". To encode them differently, you can
+  either use Malli coercion to encode values, or just turn the values to strings
+  before calling the function."
   ([name]
    (rfh/href @history name nil nil nil))
   ([name path-params]
@@ -69,9 +70,10 @@
 
   Will also trigger on-navigate callback on Reitit frontend History handler.
 
-  Note: currently collections in query parameters are encoded as field-value
-  pairs separated by &, i.e. \"?a=1&a=2\", if you want to encode them
-  differently, convert the collections to strings first.
+  By default currently collections in query parameters are encoded as field-value
+  pairs separated by &, i.e. \"?a=1&a=2\". To encode them differently, you can
+  either use Malli coercion to encode values, or just turn the values to strings
+  before calling the function.
 
   See also:
   https://developer.mozilla.org/en-US/docs/Web/API/History/pushState"
@@ -93,9 +95,10 @@
 
   Will also trigger on-navigate callback on Reitit frontend History handler.
 
-  Note: currently collections in query-parameters are encoded as field-value
-  pairs separated by &, i.e. \"?a=1&a=2\", if you want to encode them
-  differently, convert the collections to strings first.
+  By default currently collections in query parameters are encoded as field-value
+  pairs separated by &, i.e. \"?a=1&a=2\". To encode them differently, you can
+  either use Malli coercion to encode values, or just turn the values to strings
+  before calling the function.
 
   See also:
   https://developer.mozilla.org/en-US/docs/Web/API/History/replaceState"
@@ -122,9 +125,10 @@
 
   Will also trigger on-navigate callback on Reitit frontend History handler.
 
-  Note: currently collections in query-parameters are encoded as field-value
-  pairs separated by &, i.e. \"?a=1&a=2\", if you want to encode them
-  differently, convert the collections to strings first.
+  By default currently collections in query parameters are encoded as field-value
+  pairs separated by &, i.e. \"?a=1&a=2\". To encode them differently, you can
+  either use Malli coercion to encode values, or just turn the values to strings
+  before calling the function.
 
   See also:
   https://developer.mozilla.org/en-US/docs/Web/API/History/pushState
@@ -142,8 +146,11 @@
   New query params can be given as a map, or a function taking
   the old params and returning the new modified params.
 
-  Note: The query parameter values aren't coereced, so the
-  update fn will see string values for all query params."
+  The current path is matched against the routing tree, and the match data
+  (schema, coercion) is used to encode the query parameters.
+  If the current path doesn't match any route, the query parameters
+  are parsed from the path without coercion and new values
+  are also stored without coercion encoding."
   ([new-query-or-update-fn]
    (rfh/set-query @history new-query-or-update-fn))
   ([new-query-or-update-fn {:keys [replace] :as opts}]