refactor

frontend/.agents/skills/react-router/references/data-mode.md

@@ -0,0 +1,165 @@
+# Data Mode
+
+Data Mode uses data routers such as `createBrowserRouter` and renders with `<RouterProvider>`. It gives an app route objects, loaders, actions, pending UI, fetchers, and SSR primitives without adopting the Framework Vite plugin or route-module file conventions.
+
+Use this reference after the main skill identifies a Data Mode app.
+
+## Read the Local Docs by Mode
+
+Start with:
+
+```txt
+react-router/docs/start/modes.md
+react-router/docs/start/data/index.md
+```
+
+Then use the Data docs under:
+
+```txt
+react-router/docs/start/data/
+```
+
+Those files cover installation, route objects, routing, data loading, actions, navigation, pending UI, and testing. For task-specific details, read relevant files in:
+
+```txt
+react-router/docs/how-to/
+react-router/docs/explanation/
+```
+
+Always check the `[MODES: data, ...]` marker in a doc before applying it.
+
+## Data Router Shape
+
+Typical setup:
+
+```tsx
+import { createBrowserRouter, RouterProvider } from "react-router";
+
+const router = createBrowserRouter([
+  {
+    path: "/",
+    Component: Root,
+    loader: rootLoader,
+    children: [
+      { index: true, Component: Home },
+      {
+        path: "projects/:projectId",
+        Component: Project,
+        loader: projectLoader,
+      },
+    ],
+  },
+]);
+
+root.render(<RouterProvider router={router} />);
+```
+
+Look for route object arrays and APIs such as:
+
+- `createBrowserRouter`
+- `createHashRouter`
+- `createMemoryRouter`
+- `RouterProvider`
+- `loader`
+- `action`
+- `Component`
+- `ErrorBoundary`
+- `lazy`
+- `children`
+
+## Route Objects and Routing
+
+Before editing route configuration, read:
+
+```txt
+react-router/docs/start/data/routing.md
+react-router/docs/start/data/route-object.md
+```
+
+Rules:
+
+- Keep route objects outside render when possible.
+- Use nested routes for shared layouts and data boundaries.
+- Use index routes for default child content.
+- Use dynamic segments and splats according to route-object docs.
+- Prefer `Component`/`ErrorBoundary` route object properties in Data Mode examples unless the existing app uses `element` consistently.
+
+## Data and Mutations
+
+Before working on data loading or mutations, read:
+
+```txt
+react-router/docs/start/data/data-loading.md
+react-router/docs/start/data/actions.md
+```
+
+Rules:
+
+- Load route data with route `loader` functions.
+- Mutate route data with route `action` functions.
+- Prefer loaders/actions over route-level `useEffect` fetching.
+- Use `request`, `params`, and returned/throwable Responses as described in the docs.
+- Let React Router revalidate after actions unless there is a documented reason to customize revalidation.
+
+Common patterns:
+
+- Validation failure from an action: return `data({ errors, values }, { status: 400 })`, then render errors with `useActionData()` or `fetcher.data`.
+- Missing record in a loader: throw `data("Not Found", { status: 404 })` and render the route `ErrorBoundary`.
+- Search/filter data: parse `new URL(request.url).searchParams` in the loader so the URL is shareable and bookmarkable.
+
+## Forms, Fetchers, and Pending UI
+
+For forms and pending UI, read:
+
+```txt
+react-router/docs/start/data/actions.md
+react-router/docs/start/data/pending-ui.md
+react-router/docs/how-to/fetchers.md
+react-router/docs/explanation/form-vs-fetcher.md
+```
+
+Rules of thumb:
+
+- Search/filter form that updates the URL: `<Form method="get">`.
+- Mutation that should change URL/history or redirect after completion: `<Form method="post">`.
+- Mutation that should keep the user on the same page: `useFetcher` / `<fetcher.Form>`.
+- Optimistic UI: derive from `fetcher.formData` or `navigation.formData`.
+
+## Navigation and URL State
+
+Before changing navigation or search params, read:
+
+```txt
+react-router/docs/start/data/navigating.md
+react-router/docs/how-to/search-params.md
+react-router/docs/explanation/location.md
+```
+
+Rules:
+
+- Use `<Link>`/`<NavLink>` for user-initiated internal navigation.
+- Use `redirect` in loaders/actions when navigation follows data loading or mutations.
+- Use `useNavigate` for imperative client-side event navigation.
+- Treat URL params as strings and validate/parse them.
+- Preserve unrelated search params unless intentionally resetting them.
+
+## SSR in Data Mode
+
+Data Mode SSR is manual and lower-level than Framework Mode. Before implementing or changing SSR, read the Data Mode custom/SSR docs and match existing server abstractions.
+
+Start with:
+
+```txt
+react-router/docs/start/data/custom.md
+```
+
+Look for APIs like `createStaticHandler`, `createStaticRouter`, `StaticRouterProvider`, and hydration data handling in the current app before changing anything.
+
+## RSC Data
+
+If this Data Mode app uses `unstable_RSCRouteConfig`, RSC route config, or low-level RSC server APIs, also read:
+
+```txt
+references/rsc.md
+react-router/docs/how-to/react-server-components.md
+```