Merge branch 'release-next'

Author: brophdawg11

CHANGELOG.md

@@ -22,6 +22,10 @@ Changesets will do most of the heavy lifting for our releases. When changes are
 - Review the updated `CHANGELOG` files and make any adjustments necessary, then merge the PR into the `release-*` branch.
   - `find packages -name 'CHANGELOG.md' -mindepth 2 -maxdepth 2 -exec code {} \;`
 - Once the PR is merged, the release workflow will publish the updated packages to npm.
+- At this point, you can begin crafting the release notes for the eventual stable release in the root `CHANGELOG.md` file in the repo
+  - Copy the template for a new release and update the version numbers and links accordingly
+  - Copy the relevant changelog entries from all packages into the release notes and adjust accordingly
+  - Commit these changes directly to the `release-*` branch - they will not trigger a new prerelease since they do not include a changeset
 
 ### Iterating a pre-release
 
@@ -34,6 +38,7 @@ You may need to make changes to a pre-release prior to publishing a final stable
 - Wait for the release workflow to finish and the Changesets action to open its PR that will increment all versions.
 - Review the PR, make any adjustments necessary, and merge it into the `release-*` branch.
 - Once the PR is merged, the release workflow will publish the updated packages to npm.
+- Make sure you copy over the new changeset contents into stable release notes in the root `CHANGELOG.md` file in the repo
 
 ### Publishing the stable release
 
@@ -42,10 +47,11 @@ You may need to make changes to a pre-release prior to publishing a final stable
 - Wait for the release workflow to finish. The Changesets action in the workflow will open a PR that will increment all versions and generate the changelogs for the stable release.
 - Review the updated `CHANGELOG` files and make any adjustments necessary.
   - `find packages -name 'CHANGELOG.md' -mindepth 2 -maxdepth 2 -exec code {} \;`
-  - We should remove the changelogs for all pre-releases ahead of publishing the stable version.
+  - Remove the changelogs for all pre-releases
   - [TODO: We should automate this]
-- Prepare the GitHub release notes
-  - Copy the relevant changelog entries from all packages into the Release Notes and adjust accordingly, matching the format used by prior releases
+- Finalize the release notes
+  - This should already be in pretty good shape in the root `CHANGELOG.md` file in the repo
+  - Do a quick double check that all iterated prerelease changesets got copied over
 - Merge the PR into the `release-*` branch.
 - Once the PR is merged, the release workflow will publish the updated packages to npm.
 - Once the release is published:
@@ -54,7 +60,7 @@ You may need to make changes to a pre-release prior to publishing a final stable
     - `git checkout main; git merge --no-ff release-next`
   - Merge the `release-*` branch into `dev` **using a non-fast-forward merge** and push it up to GitHub
     - `git checkout dev; git merge --no-ff release-next`
-  - Convert the `[email protected]` tag to a Release on GitHub with the name `v6.x.y`
+  - Convert the `[email protected]` tag to a Release on GitHub with the name `v6.x.y` and add a deep-link to the release heading in `CHANGELOG.md`
 
 ### Hotfix releases
 

DEVELOPMENT.md

@@ -32,6 +32,7 @@
 - bbrowning918
 - BDomzalski
 - bhbs
+- bilalk711
 - bobziroll
 - BrianT1414
 - brockross

contributors.yml

@@ -93,12 +93,14 @@ You can pass a render prop as children to customize the content of the `<NavLink
 
 The `end` prop changes the matching logic for the `active` and `pending` states to only match to the "end" of the NavLink's `to` path. If the URL is longer than `to`, it will no longer be considered active.
 
-| Link                          | URL          | isActive |
-| ----------------------------- | ------------ | -------- |
-| `<NavLink to="/tasks" />`     | `/tasks`     | true     |
-| `<NavLink to="/tasks" />`     | `/tasks/123` | true     |
-| `<NavLink to="/tasks" end />` | `/tasks`     | true     |
-| `<NavLink to="/tasks" end />` | `/tasks/123` | false    |
+| Link                           | Current URL  | isActive |
+| ------------------------------ | ------------ | -------- |
+| `<NavLink to="/tasks" />`      | `/tasks`     | true     |
+| `<NavLink to="/tasks" />`      | `/tasks/123` | true     |
+| `<NavLink to="/tasks" end />`  | `/tasks`     | true     |
+| `<NavLink to="/tasks" end />`  | `/tasks/123` | false    |
+| `<NavLink to="/tasks/" end />` | `/tasks`     | false    |
+| `<NavLink to="/tasks/" end />` | `/tasks/`    | true     |
 
 **A note on links to the root route**
 

docs/components/nav-link.md

@@ -0,0 +1,136 @@
+---
+title: useBlocker
+---
+
+# `useBlocker`
+
+<details>
+  <summary>Type declaration</summary>
+
+```tsx
+declare function useBlocker(
+  shouldBlock: boolean | BlockerFunction
+): Blocker;
+
+type BlockerFunction = (args: {
+  currentLocation: Location;
+  nextLocation: Location;
+  historyAction: HistoryAction;
+}) => boolean;
+
+type Blocker =
+  | {
+      state: "unblocked";
+      reset: undefined;
+      proceed: undefined;
+      location: undefined;
+    }
+  | {
+      state: "blocked";
+      reset(): void;
+      proceed(): void;
+      location: Location;
+    }
+  | {
+      state: "proceeding";
+      reset: undefined;
+      proceed: undefined;
+      location: Location;
+    };
+
+interface Location<State = any> extends Path {
+  state: State;
+  key: string;
+}
+
+interface Path {
+  pathname: string;
+  search: string;
+  hash: string;
+}
+
+enum HistoryAction {
+  Pop = "POP",
+  Push = "PUSH",
+  Replace = "REPLACE",
+}
+```
+
+</details>
+
+The `useBlocker` hook allows you to prevent the user from navigating away from the current location, and present them with a custom UI to allow them to confirm the navigation.
+
+<docs-info>
+This only works for client-side navigations within your React Router application and will not block document requests. To prevent document navigations you will need to add your own <a href="https://developer.mozilla.org/en-US/docs/Web/API/Window/beforeunload_event" target="_blank">`beforeunload`</a> event handler.
+</docs-info>
+
+<docs-warning>
+Blocking a user from navigating is a bit of an anti-pattern, so please carefully consider any usage of this hook and use it sparingly. In the de-facto use case of preventing a user navigating away from a half-filled form, you might consider persisting unsaved state to `sessionStorage` and automatically re-filling it if they return instead of blocking them from navigating away.
+</docs-warning>
+
+```tsx
+function ImportantForm() {
+  let [value, setValue] = React.useState("");
+
+  // Block navigating elsewhere when data has been entered into the input
+  let blocker = useBlocker(
+    ({ currentLocation, nextLocation }) =>
+      value !== "" &&
+      currentLocation.pathname !== nextLocation.pathname
+  );
+
+  return (
+    <Form method="post">
+      <label>
+        Enter some important data:
+        <input
+          name="data"
+          value={value}
+          onChange={(e) => setValue(e.target.value)}
+        />
+      </label>
+      <button type="submit">Save</button>
+
+      {blocker.state === "blocked" ? (
+        <div>
+          <p>Are you sure you want to leave?</p>
+          <button onClick={() => blocker.proceed()}>
+            Proceed
+          </button>
+          <button onClick={() => blocker.reset()}>
+            Cancel
+          </button>
+        </div>
+      ) : null}
+    </Form>
+  );
+}
+```
+
+For a more complete example, please refer to the [example][example] in the repository.
+
+## Properties
+
+### `state`
+
+The current state of the blocker
+
+- `unblocked` - the blocker is idle and has not prevented any navigation
+- `blocked` - the blocker has prevented a navigation
+- `proceeding` - the blocker is proceeding through from a blocked navigation
+
+### `location`
+
+When in a `blocked` state, this represents the location to which we blocked a navigation. When in a `proceeding` state, this is the location being navigated to after a `blocker.proceed()` call.
+
+## Methods
+
+### `proceed()`
+
+When in a `blocked` state, you may call `blocker.proceed()` to proceed to the blocked location.
+
+### `reset()`
+
+When in a `blocked` state, you may call `blocker.reset()` to return the blocker back to an `unblocked` state and leave the user at the current location.
+
+[example]: https://github.com/remix-run/react-router/tree/main/examples/navigation-blocking

docs/hooks/use-blocker.md

@@ -107,7 +107,7 @@ function SomeComponent() {
 
 ## Methods
 
-## `fetcher.load()`
+### `fetcher.load(href, options)`
 
 Loads data from a route loader.
 
@@ -133,7 +133,13 @@ If you find yourself calling this function inside of click handlers, you can pro
 
 <docs-info>Any `fetcher.load` calls that are active on the page will be re-executed as part of revalidation (either after a navigation submission, another fetcher submission, or a `useRevalidator()` call)</docs-info>
 
-## `fetcher.submit()`
+#### `options.unstable_flushSync`
+
+The `unstable_flushSync` option tells React Router DOM to wrap the initial state update for this `fetcher.load` in a [`ReactDOM.flushSync`][flush-sync] call instead of the default [`React.startTransition`][start-transition]. This allows you to perform synchronous DOM actions immediately after the update is flushed to the DOM.
+
+<docs-warning>Please note that this API is marked unstable and may be subject to breaking changes without a major release</docs-warning>
+
+### `fetcher.submit()`
 
 The imperative version of `<fetcher.Form>`. If a user interaction should initiate the fetch, you should use `<fetcher.Form>`. But if you, the programmer are initiating the fetch (not in response to a user clicking a button, etc.), then use this function.
 
@@ -279,3 +285,5 @@ fetcher.formMethod; // "post"
 [api-development-strategy]: ../guides/api-development-strategy
 [use-submit]: ./use-submit
 [use-fetchers]: ./use-fetchers
+[flush-sync]: https://react.dev/reference/react-dom/flushSync
+[start-transition]: https://react.dev/reference/react/startTransition

docs/hooks/use-fetcher.md

@@ -20,6 +20,8 @@ interface NavigateOptions {
   state?: any;
   preventScrollReset?: boolean;
   relative?: RelativeRoutingType;
+  unstable_flushSync?: boolean;
+  unstable_viewTransition?: boolean;
 }
 
 type RelativeRoutingType = "route" | "path";
@@ -89,6 +91,14 @@ function EditContact() {
 }
 ```
 
+## `options.unstable_flushSync`
+
+The `unstable_flushSync` option tells React Router DOM to wrap the initial state update for this navigation in a [`ReactDOM.flushSync`][flush-sync] call instead of the default [`React.startTransition`][start-transition]. This allows you to perform synchronous DOM actions immediately after the update is flushed to the DOM.
+
+<docs-warning>`unstable_flushSync` only works when using a data router, see [Picking a Router][picking-a-router]</docs-warning>
+
+<docs-warning>Please note that this API is marked unstable and may be subject to breaking changes without a major release</docs-warning>
+
 ## `options.unstable_viewTransition`
 
 The `unstable_viewTransition` option enables a [View Transition][view-transitions] for this navigation by wrapping the final state update in `document.startViewTransition()`. If you need to apply specific styles for this view transition, you will also need to leverage the [`unstable_useViewTransitionState()`][use-view-transition-state].
@@ -107,3 +117,5 @@ The `unstable_viewTransition` option enables a [View Transition][view-transition
 [use-view-transition-state]: ../hooks//use-view-transition-state
 [view-transitions]: https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API
 [picking-a-router]: ../routers/picking-a-router
+[flush-sync]: https://react.dev/reference/react-dom/flushSync
+[start-transition]: https://react.dev/reference/react/startTransition

docs/hooks/use-navigate.md

@@ -0,0 +1,87 @@
+---
+title: unstable_usePrompt
+---
+
+# `unstable_usePrompt`
+
+<details>
+  <summary>Type declaration</summary>
+
+```tsx
+declare function unstable_usePrompt({
+  when,
+  message,
+}: {
+  when: boolean | BlockerFunction;
+  message: string;
+}) {
+
+type BlockerFunction = (args: {
+  currentLocation: Location;
+  nextLocation: Location;
+  historyAction: HistoryAction;
+}) => boolean;
+
+interface Location<State = any> extends Path {
+  state: State;
+  key: string;
+}
+
+interface Path {
+  pathname: string;
+  search: string;
+  hash: string;
+}
+
+enum HistoryAction {
+  Pop = "POP",
+  Push = "PUSH",
+  Replace = "REPLACE",
+}
+```
+
+</details>
+
+The `unstable_usePrompt` hook allows you to prompt the user for confirmation via [`window.confirm`][window-confirm] prior to navigating away from the current location.
+
+<docs-info>
+This only works for client-side navigations within your React Router application and will not block document requests. To prevent document navigations you will need to add your own <a href="https://developer.mozilla.org/en-US/docs/Web/API/Window/beforeunload_event" target="_blank">`beforeunload`</a> event handler.
+</docs-info>
+
+<docs-warning>
+Blocking a user from navigating is a bit of an anti-pattern, so please carefully consider any usage of this hook and use it sparingly. In the de-facto use case of preventing a user navigating away from a half-filled form, you might consider persisting unsaved state to `sessionStorage` and automatically re-filling it if they return instead of blocking them from navigating away.
+</docs-warning>
+
+<docs-warning>
+We do not plan to remove the `unstable_` prefix from this hook because the behavior is non-deterministic across browsers when the prompt is open, so React Router cannot guarantee correct behavior in all scenarios.  To avoid this non-determinism, we recommend using `useBlocker` instead which also gives you control over the confirmation UX.
+</docs-warning>
+
+```tsx
+function ImportantForm() {
+  let [value, setValue] = React.useState("");
+
+  // Block navigating elsewhere when data has been entered into the input
+  unstable_usePrompt({
+    message: "Are you sure?",
+    when: ({ currentLocation, nextLocation }) =>
+      value !== "" &&
+      currentLocation.pathname !== nextLocation.pathname,
+  });
+
+  return (
+    <Form method="post">
+      <label>
+        Enter some important data:
+        <input
+          name="data"
+          value={value}
+          onChange={(e) => setValue(e.target.value)}
+        />
+      </label>
+      <button type="submit">Save</button>
+    </Form>
+  );
+}
+```
+
+[window-confirm]: https://developer.mozilla.org/en-US/docs/Web/API/Window/confirm

docs/hooks/use-prompt.md

@@ -160,5 +160,13 @@ Because submissions are navigations, the options may also contain the other navi
 - `state`
 - `unstable_viewTransition`
 
+### `options.unstable_flushSync`
+
+The `unstable_flushSync` option tells React Router DOM to wrap the initial state update for this submission in a [`ReactDOM.flushSync`][flush-sync] call instead of the default [`React.startTransition`][start-transition]. This allows you to perform synchronous DOM actions immediately after the update is flushed to the DOM.
+
+<docs-warning>Please note that this API is marked unstable and may be subject to breaking changes without a major release</docs-warning>
+
 [pickingarouter]: ../routers/picking-a-router
 [form]: ../components/form
+[flush-sync]: https://react.dev/reference/react-dom/flushSync
+[start-transition]: https://react.dev/reference/react/startTransition