@alxia/react-router 0.25.0 → 0.26.0

package/README.md

@@ -1028,6 +1028,22 @@ export const action = events.action; // POST
 See the [subscription guide](https://github.com/softistx/alxia/blob/develop/packages/react-router/docs/guide/subscriptions.md)
 for the rules, the options and the errors.
 
+## A UI library's links through React Router
+
+A design system that renders its links through a component of its own (a
+`LinkComponentProvider`) hands it an `href`, while React Router's `Link` takes
+`to`. `@alxia/react-router/link` (`react` and `react-router` are its only
+imports) exports the adapter, so no app copies it:
+
+```tsx
+// app/root.tsx
+import { RouterLink } from '@alxia/react-router/link';
+
+<LinkComponentProvider component={RouterLink}>
+	<Outlet />
+</LinkComponentProvider>
+```
+
 ## A list whose state is the URL
 
 `@alxia/react-router/lists` (`react` and `react-router` are its only imports; every hook renders on the server)
@@ -1306,6 +1322,12 @@ From `@alxia/react-router/lists` (`react` and `react-router` are its only import
 | `usePagedRows(firstPage, rowsOf, { cursorParam?, nextOf? }?)`, `PagedRows`, `PagedRowsOptions` | `{ rows, next, loading, error, loadMore }`: appends the pages the same route answers to `?<cursorParam>=<next>` (default `after`, `nextOf` default `page.next`) through `useFetcher`; starts over when `firstPage` is another object; a failure keeps the rows and sets `error` (an answer that is not a page), and data that is not a page is ignored |
 | `orFailed(after, run)`, `FAILED`, `isFailedPage(value)`, `FailedPage` | the loader half of `usePagedRows`: `run()`'s answer; an error is rethrown when `after` is empty, and with an `after` it answers `FAILED` (`{ failed: true }`, typed `Promise<T \| FailedPage>`), except a 3xx `Response`, which is rethrown. `isFailedPage` narrows an answer |
 
+From `@alxia/react-router/link` (`react` and `react-router` are its only imports; it renders on the server):
+
+| export | |
+| --- | --- |
+| `RouterLink`, `RouterLinkProps` | React Router's `Link` as a UI library's link component: takes `href` (or `to`), spreads `className`, `children`, `ref` and every anchor prop onto the `<a>`, keeps `Link`'s own props (`replace`, `prefetch`, `reloadDocument`, ...) |
+
 From `@alxia/react-router/subscription` (no import, no peer):
 
 | export | |

package/dist/link/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `@alxia/react-router/link`: React Router's `Link` as the link component of
+ * a UI library. `react` and `react-router` are its only imports, and it
+ * renders on the server.
+ */
+export { RouterLink, type RouterLinkProps } from './router-link';
+//# sourceMappingURL=index.d.ts.map

package/dist/link/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/link/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC"}

package/dist/link/index.js

@@ -0,0 +1,16 @@
+// src/link/router-link.ts
+import { createElement } from "react";
+import { Link } from "react-router";
+function RouterLink({
+  href,
+  to,
+  ...props
+}) {
+  return createElement(Link, { ...props, to: href ?? to });
+}
+export {
+  RouterLink
+};
+
+//# debugId=D9C7D4DF88CF5C0964756E2164756E21
+//# sourceMappingURL=index.js.map

package/dist/link/index.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/link/router-link.ts"],
+  "sourcesContent": [
+    "import { createElement, type ReactElement, type RefAttributes } from 'react';\nimport { Link, type LinkProps, type To } from 'react-router';\n\n/**\n * The props of {@link RouterLink}: React Router's `Link` props, with the\n * destination given as `href` (what a design system's link component hands\n * over) or as `to` (React Router's own name), never both.\n */\nexport type RouterLinkProps = Omit<LinkProps, 'to'> &\n\tRefAttributes<HTMLAnchorElement> &\n\t({ href: To; to?: undefined } | { to: To; href?: undefined });\n\n/**\n * React Router's `Link` for a UI library that renders its links through a\n * component of its own (a `LinkComponentProvider`): it receives `href` and\n * spreads every other prop (`className`, `children`, `aria-*`, `ref`, ...)\n * onto the anchor. Navigation stays client-side and `<Link>`'s own props\n * (`prefetch`, `replace`, `reloadDocument`, ...) still apply.\n *\n * ```tsx\n * <LinkComponentProvider component={RouterLink}>...</LinkComponentProvider>\n * ```\n */\nexport function RouterLink({\n\thref,\n\tto,\n\t...props\n}: RouterLinkProps): ReactElement {\n\t// The union guarantees one of the two is set; TypeScript cannot see it\n\t// through the destructuring, hence the cast.\n\treturn createElement(Link, { ...props, to: (href ?? to) as To });\n}\n"
+  ],
+  "mappings": ";AAAA;AACA;AAsBO,SAAS,UAAU;AAAA,EACzB;AAAA,EACA;AAAA,KACG;AAAA,GAC8B;AAAA,EAGjC,OAAO,cAAc,MAAM,KAAK,OAAO,IAAK,QAAQ,GAAU,CAAC;AAAA;",
+  "debugId": "D9C7D4DF88CF5C0964756E2164756E21",
+  "names": []
+}

package/dist/link/router-link.d.ts

@@ -0,0 +1,27 @@
+import { type ReactElement, type RefAttributes } from 'react';
+import { type LinkProps, type To } from 'react-router';
+/**
+ * The props of {@link RouterLink}: React Router's `Link` props, with the
+ * destination given as `href` (what a design system's link component hands
+ * over) or as `to` (React Router's own name), never both.
+ */
+export type RouterLinkProps = Omit<LinkProps, 'to'> & RefAttributes<HTMLAnchorElement> & ({
+    href: To;
+    to?: undefined;
+} | {
+    to: To;
+    href?: undefined;
+});
+/**
+ * React Router's `Link` for a UI library that renders its links through a
+ * component of its own (a `LinkComponentProvider`): it receives `href` and
+ * spreads every other prop (`className`, `children`, `aria-*`, `ref`, ...)
+ * onto the anchor. Navigation stays client-side and `<Link>`'s own props
+ * (`prefetch`, `replace`, `reloadDocument`, ...) still apply.
+ *
+ * ```tsx
+ * <LinkComponentProvider component={RouterLink}>...</LinkComponentProvider>
+ * ```
+ */
+export declare function RouterLink({ href, to, ...props }: RouterLinkProps): ReactElement;
+//# sourceMappingURL=router-link.d.ts.map

package/dist/link/router-link.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router-link.d.ts","sourceRoot":"","sources":["../../src/link/router-link.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,OAAO,CAAC;AAC7E,OAAO,EAAQ,KAAK,SAAS,EAAE,KAAK,EAAE,EAAE,MAAM,cAAc,CAAC;AAE7D;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,GAClD,aAAa,CAAC,iBAAiB,CAAC,GAChC,CAAC;IAAE,IAAI,EAAE,EAAE,CAAC;IAAC,EAAE,CAAC,EAAE,SAAS,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,EAAE,CAAC;IAAC,IAAI,CAAC,EAAE,SAAS,CAAA;CAAE,CAAC,CAAC;AAE/D;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,EAC1B,IAAI,EACJ,EAAE,EACF,GAAG,KAAK,EACR,EAAE,eAAe,GAAG,YAAY,CAIhC"}

package/docs/README.md

@@ -20,6 +20,7 @@ installable and usable offline, wording an API's refusals, the BFF session, a Gr
 | [Installable and offline](guide/pwa.md) | making the app installable and usable offline: the subpaths of `@alxia/react-router/pwa`, the service worker (`startWorker`, `/pwa/worker`), its build by `alxia()` or `buildWorker` (`/pwa/build`), its contract and cache names, which requests the worker caches and which responses it stores, the precache list read from a build, or clearing the caches at sign-out |
 | [An API's refusals](guide/errors.md) | wording a GraphQL API's refusals for the pages: recognising an `ApiError`, the request id, the page a request is for, the catalogue store, the form checks in the API's words, the provider, and the loaders, the error page and the actions that answer with it, the JSON actions with their CSRF check and fetcher hook, calling the API from a loader (`apiCallFailure`), and keeping the catalogue fresh (`@alxia/react-router/errors`) |
 | [A BFF session](guide/session.md) | redirecting after sign-in to a page of the site and nowhere else, the sign-in pages' paths, the session's cookies, the sign-in flow (where an answer lands, a refused code, the viewer, sign-out; `@alxia/react-router/session`), the pages a mail's link opens (a magic link, a password reset: `authLinks`), the page's hooks (sign-out, a mail link's parameter, a one-code field; `@alxia/react-router/session/react`), and the step-up's state and the props it gives the UI (`@alxia/react-router/session/model`) |
+| [Links through React Router](guide/link.md) | `RouterLink`, React Router's `Link` as the link component of a UI library that hands `href` and spreads anchor props; `@alxia/react-router/link` |
 | [Lists whose state is the URL](guide/lists.md) | a search and filters in the address bar that drop the cursor (`useSearchChange`), a skeleton while the same page reloads (`useSameRouteLoading`), and a load-more button that appends pages by cursor and keeps the rows when one fails (`usePagedRows`); `@alxia/react-router/lists` |
 | [Subscriptions for a BFF](guide/subscriptions.md) | showing a GraphQL subscription in the browser without giving it the API's token or a way to write a document: a resource route with a map of operation names to the server's documents, the same-site check, the bearer from the session, extra upstream headers, a heartbeat, abort propagation, size limits and a 429 passed through with `retryAfter` (`@alxia/react-router/subscription`) |
 | [Troubleshooting](troubleshooting.md) | something went wrong and you have the message, or a page streams, hydrates or reads its context unlike you expected |

package/docs/guide/link.md

@@ -0,0 +1,32 @@
+# Links through React Router
+
+A UI library that renders its links through a component of its own (a
+`LinkComponentProvider`) hands that component an `href` and spreads every other
+prop onto the anchor. React Router's `Link` takes `to`, so an app adapts it.
+`@alxia/react-router/link` exports that adapter. `react` and `react-router` are
+its only imports, and it renders on the server.
+
+```tsx
+// app/root.tsx
+import { RouterLink } from '@alxia/react-router/link';
+
+export default function App() {
+	return (
+		<LinkComponentProvider component={RouterLink}>
+			<Outlet />
+		</LinkComponentProvider>
+	);
+}
+```
+
+## What it does
+
+- `href` (or `to`, React Router's own name, never both) is the destination: a
+  string or a `To` object.
+- An external target (`https://…`, `mailto:`, `//host`) renders a plain anchor with that `href`; React Router's `Link` already handles it.
+- `className`, `children`, `ref`, `aria-*`, `target` and every other anchor prop
+  reach the `<a>`.
+- `Link`'s own props (`replace`, `prefetch`, `reloadDocument`, `state`, ...) still
+  apply, so a link can opt out of client-side navigation.
+
+`RouterLinkProps` is the type of its props, for a wrapper of your own.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@alxia/react-router",
-	"version": "0.25.0",
+	"version": "0.26.0",
 	"description": "alxia as the server of a React Router framework app: server rendering behind the app's hooks, loaders reading its typed context, the client's assets served; the code with no UI an installable app shares (`/pwa`), its hooks (`/pwa/react`), `noCache` for the worker's script (`/pwa/server`), the service worker on Workbox (`/pwa/worker`) and its build (`/pwa/build`), an API's refusals worded for the page (`/errors`), the BFF session: cookies, sign-in, step-up and mail links (`/session`), its page hooks (`/session/react`) and what it shares with the page (`/session/model`), a GraphQL subscription relayed to the browser over SSE (`/subscription`), the page's CSP nonce and inline boot scripts (`/document`) and a streaming `entry.server` (`/entry`)",
 	"license": "MIT",
 	"type": "module",
@@ -87,6 +87,11 @@
 			"import": "./dist/lists/index.js",
 			"default": "./dist/lists/index.js"
 		},
+		"./link": {
+			"types": "./dist/link/index.d.ts",
+			"import": "./dist/link/index.js",
+			"default": "./dist/link/index.js"
+		},
 		"./subscription": {
 			"types": "./dist/subscription/index.d.ts",
 			"import": "./dist/subscription/index.js",
@@ -121,6 +126,7 @@
 			"src/session/react/index.ts",
 			"src/subscription/index.ts",
 			"src/lists/index.ts",
+			"src/link/index.ts",
 			"src/document/index.ts",
 			"src/entry/index.ts",
 			"src/pwa/worker/index.ts",