From ebdb5f9e283ca3bc265d5e90c2b132b2ad24ad06 Mon Sep 17 00:00:00 2001
From: Evgenii Alaev <alaev89@yandex-team.ru>
Date: Thu, 30 Jul 2026 15:37:41 +0200
Subject: [PATCH] docs: add migration guide from 3 to 4

---
 README.md                |   4 ++
 docs/migration-3-to-4.md | 117 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 121 insertions(+)
 create mode 100644 docs/migration-3-to-4.md

diff --git a/README.md b/README.md
index 677224b..5c06c64 100644
--- a/README.md
+++ b/README.md
@@ -109,6 +109,10 @@ Distributed under the MIT License. See [LICENSE](LICENSE) for details.
 
 React date and time controls for Gravity UI apps — date/time pickers, calendars, and absolute/relative range selectors built on `@gravity-ui/date-utils`.
 
+### Migration notes
+
+For migration guidance from 3.x to 4.x, see [docs/migration-3-to-4.md](docs/migration-3-to-4.md).
+
 ### When to use
 
 - A single date or date-time input: `DatePicker`, `DateField`.
diff --git a/docs/migration-3-to-4.md b/docs/migration-3-to-4.md
new file mode 100644
index 0000000..9c7ed52
--- /dev/null
+++ b/docs/migration-3-to-4.md
@@ -0,0 +1,117 @@
+# Migration guide: 3.x → 4.x
+
+This note summarizes the main behavior changes that are relevant for migration from version 3 to version 4.
+
+## 1. RelativeDateField: `onUpdate` is now emitted only for valid input
+
+### Before
+
+The component could report intermediate values while the user was typing an incomplete or invalid relative expression.
+
+```tsx
+<RelativeDateField onUpdate={(value) => console.log(value)} />
+```
+
+Example flow:
+
+- typing `now - 1` could already trigger `onUpdate('now - 1')`
+- invalid draft text could still propagate while the input was being edited
+
+### After
+
+`onUpdate` is emitted only when the current input is valid.
+
+```tsx
+<RelativeDateField onUpdate={(value) => console.log(value)} />
+```
+
+Example flow:
+
+- typing `now - 1` does not emit until the expression becomes valid
+- invalid draft text is kept in the field, but the last committed value remains unchanged until the input becomes valid again
+
+### What to change in your code
+
+If your application relied on “live updates during typing”, move the logic to the moment when the value becomes valid.
+
+```tsx
+// Before
+const handleUpdate = (value) => {
+  setState(value);
+};
+
+// After
+const handleUpdate = (value) => {
+  if (value !== null) {
+    setState(value);
+  }
+};
+```
+
+## 2. DateField / RangeDateField: intermediate invalid dates are now preserved instead of immediately emitting
+
+### Before
+
+While the user was typing, an incomplete or invalid date could be forced through the update flow quickly, and the component could emit values before the input was finalized.
+
+```tsx
+<DateField onUpdate={(value) => console.log(value)} />
+```
+
+### After
+
+The component temporarily preserves invalid or incomplete input internally and does not emit `onUpdate` until the value is finalized on blur.
+
+```tsx
+<DateField onUpdate={(value) => console.log(value)} />
+```
+
+Example flow:
+
+- typing `31 April 2024` keeps the field in an intermediate state
+- the value is normalized only when the field loses focus
+
+### What to change in your code
+
+If your consumer expects “instant updates on every keystroke”, switch to a blur-based or validation-based flow.
+
+```tsx
+// Before
+const handleUpdate = (value) => {
+  saveValue(value);
+};
+
+// After
+const handleBlur = () => {
+  if (currentValueRef.current) {
+    saveValue(currentValueRef.current);
+  }
+};
+```
+
+## 3. Calendar selection styling changed
+
+### Before
+
+The visual treatment of the selection end text color was different.
+
+### After
+
+The end of the selection uses updated text color styling.
+
+### What to change in your code
+
+If you use custom CSS overrides for calendar selection visuals, review those styles after upgrading.
+
+## 4. Additional behavior changes worth checking
+
+- Calendar now supports multi-selection.
+- RelativeRangeDatePicker accepts `null` values in preset handling.
+- DateField internals were refactored around incomplete/invalid state handling.
+
+## Migration checklist
+
+- Review handlers that depend on `onUpdate` during typing.
+- Make sure your form logic handles “invalid/incomplete intermediate input” without assuming it is committed.
+- Check custom styles for calendar selection visuals.
+- Re-test date entry flows for blur and validation behavior.