docs: explanations work

Author: ryanflorence

docs/explanation/code-splitting.md

@@ -4,6 +4,46 @@ title: Automatic Code Splitting
 
 # Automatic Code Splitting
 
-<docs-warning>
-  This document is a work in progress. There's not much to see here (yet).
-</docs-warning>
+When using React Router's framework features, your application is automatically code split to improve the performance of initial load times when users visit your application.
+
+## Code Splitting by Route
+
+Consider this simple route config:
+
+```tsx filename=routes.ts
+export default [
+  route("/contact", "./contact.tsx"),
+  route("/about", "./about.tsx"),
+];
+```
+
+Instead of bundling all routes into a single giant build, the modules referenced (`contact.tsx` and `about.tsx`) become entry points to the bundler.
+
+Because these entry points are coupled to URL segments, React Router knows just from a URL which bundles are needed in the browser, and more importantly, which are not.
+
+If the user visits `"/about"` then the bundles for `about.tsx` will be loaded but not `contact.tsx`. This ensures drastically reduces the JavaScript footprint for initial page loads and speeds up your application.
+
+## Removal of Server Code
+
+Any server-only Route Module APIs will be removed from the bundles. Consider this route module:
+
+```tsx
+export async function loader() {
+  return { message: "hello" };
+}
+
+export async function action() {
+  console.log(Date.now());
+  return { ok: true };
+}
+
+export async function headers() {
+  return { "Cache-Control": "max-age=300" };
+}
+
+export default function Component({ loaderData }) {
+  return <div>{loaderData.message}</div>;
+}
+```
+
+After building for the browser, only the `Component` will still be in the bundle, so you can use server-only code in the other module exports.

docs/explanation/picking-a-router.md

@@ -1,5 +1,6 @@
 ---
 title: Picking a Router
+hidden: true
 ---
 
 ## TODO:

docs/explanation/race-conditions.md

@@ -4,6 +4,80 @@ title: Race Conditions
 
 # Race Conditions
 
-<docs-warning>
-  This document is a work in progress. There's not much to see here (yet).
-</docs-warning>
+While impossible to eliminate every possible race condition in your application, React Router automatically handles the most common race conditions found in web user interfaces.
+
+## Browser Behavior
+
+React Router's handling of network concurrency is heavily inspired by the behavior of web browsers when processing documents.
+
+Consider clicking a link to a new document, and then clicking a different link before the new page has finished loading. The browser will:
+
+1. cancel the first request
+2. immediately processes the new navigation
+
+This behavior includes form submissions. When a pending form submission is interrupted by a new one, the first is canceled and the new submission is immediately processed.
+
+## React Router Behavior
+
+Like the browser, interrupted navigations with links and form submissions will cancel in flight data requests and immediately process the new event.
+
+Fetchers are a bit more nuanced since they are not singleton events like navigation. Fetchers can't interrupt a other fetcher instances, but they can interrupt themselves and the behavior is the same as everything else: cancel the interrupted request and immediately process the new one.
+
+Fetchers do, however, interact with each when it comes to revalidation. After a fetcher's action request returns to the browser, a revalidation for all page data is sent. This means multiple revalidation requests can be in-flight at the same time. React Router will commit all "fresh" revalidation responses and cancel any stale requests. A stale request is any request that started _earlier_ than one that has returned.
+
+This management of the network prevents the most common UI bugs caused by network race conditions.
+
+Since networks are unpredictable, and your server still processes these cancelled requests, your backend may still experience race conditions and have potential data integrity issues. These risks are the same risks as using default browser behavior with plain HTML `<forms>`, which we consider to be low, and outside the scope of React Router.
+
+## Practical Benefits
+
+Consider building a type-ahead combobox. As the user types, you send a request to the server. As they type each new character you send a new request. It's important to not show the user results for a value that's not in the text field anymore.
+
+When using a fetcher, this is automatically managed for you. Consider this pseudo-code:
+
+```tsx
+// route("/city-search", "./search-cities.ts")
+export async function loader({ request }) {
+  const { searchParams } = new URL(request.url);
+  return searchCities(searchParams.get("q"));
+}
+```
+
+```tsx
+export function CitySearchCombobox() {
+  const fetcher = useFetcher();
+
+  return (
+    <fetcher.Form action="/city-search">
+      <Combobox aria-label="Cities">
+        <ComboboxInput
+          name="q"
+          onChange={(event) =>
+            // submit the form onChange to get the list of cities
+            fetcher.submit(event.target.form)
+          }
+        />
+
+        {fetcher.data ? (
+          <ComboboxPopover className="shadow-popup">
+            {fetcher.data.length > 0 ? (
+              <ComboboxList>
+                {fetcher.data.map((city) => (
+                  <ComboboxOption
+                    key={city.id}
+                    value={city.name}
+                  />
+                ))}
+              </ComboboxList>
+            ) : (
+              <span>No results found</span>
+            )}
+          </ComboboxPopover>
+        ) : null}
+      </Combobox>
+    </fetcher.Form>
+  );
+}
+```
+
+Calls to `fetcher.submit` will cancel pending requests on that fetcher automatically. This ensures you never show the user results for a request for a different input value.

docs/explanation/route-matching.md

@@ -1,9 +1,7 @@
 ---
 title: Route Matching
+hidden: true
+# want to explain how the matching algorithm works with any potential gotchas
 ---
 
 # Route Matching
-
-<docs-warning>
-  This document is a work in progress. There's not much to see here (yet).
-</docs-warning>

docs/explanation/type-safety.md

@@ -1,12 +1,10 @@
 ---
-title: Type safety
+title: Type Safety
 ---
 
-# Type safety
+# Type Safety
 
-<docs-info>
 If you haven't done so already, check out our guide for <a href="../framework/how-to/setting-up-type-safety">setting up type safety</a> in a new project.
-</docs-info>
 
 React Router generates types for each route in your app that you can use to get type safety for each route module export.