netjes 0.0.0-stage → 0.0.2

package/src/define-page.tsx

@@ -0,0 +1,41 @@
+import type { ComponentType, FunctionComponent, ReactNode } from 'react';
+import type { LayoutProps } from './modules.ts';
+import { type StandardSchemaV1, parseWith } from './schema.ts';
+
+export type { StandardSchemaV1 } from './schema.ts';
+
+/**
+ * Declares a page whose props (sent by the C# loader) are validated with a Standard Schema before rendering,
+ * so the component receives parsed, typed props instead of trusting the server's JSON.
+ */
+export function definePage<Schema extends StandardSchemaV1>(
+  schema: Schema,
+  Page: ComponentType<StandardSchemaV1.InferOutput<Schema>>,
+): FunctionComponent<Record<string, unknown>> {
+  function ValidatedPage(props: Record<string, unknown>) {
+    const parsed = parseWith(schema, props, 'props') as StandardSchemaV1.InferOutput<Schema> & object;
+    return <Page {...parsed} />;
+  }
+  ValidatedPage.displayName = `definePage(${Page.displayName ?? Page.name ?? 'Page'})`;
+  return ValidatedPage;
+}
+
+/**
+ * Declares a layout whose loader props (from `MapLayoutLoader` in C#) are validated with a Standard Schema. The
+ * component gets the parsed props next to `children` and `params`.
+ */
+export function defineLayout<Schema extends StandardSchemaV1>(
+  schema: Schema,
+  Layout: ComponentType<StandardSchemaV1.InferOutput<Schema> & LayoutProps>,
+): FunctionComponent<LayoutProps & Record<string, unknown>> {
+  function ValidatedLayout({ children, params, ...props }: LayoutProps & Record<string, unknown>): ReactNode {
+    const parsed = parseWith(schema, props, 'layout props') as StandardSchemaV1.InferOutput<Schema> & object;
+    return (
+      <Layout {...parsed} params={params}>
+        {children}
+      </Layout>
+    );
+  }
+  ValidatedLayout.displayName = `defineLayout(${Layout.displayName ?? Layout.name ?? 'Layout'})`;
+  return ValidatedLayout;
+}

package/src/document.tsx

@@ -0,0 +1,49 @@
+import type { ReactNode } from 'react';
+import { DEFERRED_BOOTSTRAP } from './deferred.ts';
+import { DATA_ELEMENT_ID, type DocumentInfo, SHELL_END_ID } from './payload.ts';
+
+type DocumentProps = { info: DocumentInfo; dataJson: string; children: ReactNode };
+
+/**
+ * The `<html>` shell around every page. React renders and hydrates the whole document, so `<title>`, `<meta>`
+ * and `<link>` rendered by pages and layouts end up in the head.
+ *
+ * Documents stream, so the client entry is `async`: it hydrates the shell as soon as the shell is in, not once the
+ * last Suspense boundary has arrived. Everything it reads comes before the content: the deferred-values bootstrap in
+ * the head, the payload first in the body. The empty element at the end of the body is the last thing in the shell,
+ * which the client entry waits for before it hydrates: a cached entry can run long before the parser gets there.
+ */
+export function Document({ info, dataJson, children }: DocumentProps) {
+  const { nonce } = info;
+  return (
+    <html lang={info.lang}>
+      <head>
+        <meta charSet="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        {/* Vite reads the nonce from here for the styles it injects. */}
+        {nonce && <meta property="csp-nonce" nonce={nonce} />}
+        {/* Collects Page.Defer values streamed in before the client script runs. A client render finds it in the
+            document the server wrote; one React creates would never run. */}
+        {!info.clientRender && <script nonce={nonce} dangerouslySetInnerHTML={{ __html: DEFERRED_BOOTSTRAP }} />}
+        {info.assets.stylesheets.map((href) => (
+          <link key={href} rel="stylesheet" href={href} nonce={nonce} />
+        ))}
+        {info.devStyles?.map((style) => (
+          <style key={style.id} data-vite-dev-id={style.id} nonce={nonce} dangerouslySetInnerHTML={{ __html: style.css }} />
+        ))}
+        {info.assets.modulePreloads.map((href) => (
+          <link key={href} rel="modulepreload" href={href} nonce={nonce} />
+        ))}
+        {info.assets.scripts.map((src) => (
+          <script key={src} type="module" src={src} async nonce={nonce} />
+        ))}
+      </head>
+      <body>
+        {/* Already escaped for HTML by the server; the client reads it back verbatim to hydrate. */}
+        <script id={DATA_ELEMENT_ID} type="application/json" nonce={nonce} dangerouslySetInnerHTML={{ __html: dataJson }} />
+        {children}
+        <template id={SHELL_END_ID} />
+      </body>
+    </html>
+  );
+}

package/src/draft-mode.ts

@@ -0,0 +1,6 @@
+import { usePagePayload } from './router.tsx';
+
+/** Whether this page was rendered in draft mode (`IDraftMode.Enable()` on the server), like Next.js's `draftMode()`. */
+export function useDraftMode(): { isEnabled: boolean } {
+  return { isEnabled: usePagePayload().draftMode === true };
+}

package/src/dynamic.tsx

@@ -0,0 +1,64 @@
+import { type ComponentType, type ReactNode, Suspense, lazy, useSyncExternalStore } from 'react';
+
+const subscribe = () => () => {};
+
+/** False on the server and while hydrating, true afterwards (and for client-only renders): hydration-safe. */
+function useHydrated() {
+  return useSyncExternalStore(
+    subscribe,
+    () => true,
+    () => false,
+  );
+}
+
+function ClientOnly({ fallback, children }: { fallback: ReactNode; children: ReactNode }) {
+  return useHydrated() ? children : fallback;
+}
+
+/** Options for `dynamic`. */
+export type DynamicOptions = {
+  /** Server-render the component (default), or only render it in the browser (`false`), e.g. for code that needs `window`. */
+  ssr?: boolean;
+  /** Shown while the module loads, and on the server when `ssr` is false. */
+  loading?: ComponentType;
+};
+
+/**
+ * Like `next/dynamic`: a component whose module loads on demand, in its own chunk.
+ * `dynamic(() => import('./Chart.tsx'), { loading: Spinner })`.
+ */
+export function dynamic<P extends object>(
+  load: () => Promise<{ default: ComponentType<P> } | ComponentType<P>>,
+  options: DynamicOptions = {},
+): ComponentType<P> {
+  const Lazy = lazy(async () => {
+    const module = await load();
+    return { default: typeof module === 'function' ? module : module.default };
+  });
+  const Loading = options.loading;
+
+  function Dynamic(props: P) {
+    const fallback = Loading ? <Loading /> : null;
+    const content = (
+      <Suspense fallback={fallback}>
+        <Lazy {...props} />
+      </Suspense>
+    );
+    return options.ssr === false ? <ClientOnly fallback={fallback}>{content}</ClientOnly> : content;
+  }
+  Dynamic.displayName = 'Dynamic';
+  return Dynamic;
+}
+
+/** A component that renders only in the browser, after hydration; `fallback` (default nothing) until then and on the server. */
+export function clientOnly<P extends object>(Component: ComponentType<P>, options: { fallback?: ReactNode } = {}): ComponentType<P> {
+  function ClientOnlyComponent(props: P) {
+    return (
+      <ClientOnly fallback={options.fallback ?? null}>
+        <Component {...props} />
+      </ClientOnly>
+    );
+  }
+  ClientOnlyComponent.displayName = `clientOnly(${Component.displayName ?? Component.name ?? 'Component'})`;
+  return ClientOnlyComponent;
+}

package/src/form-data.ts

@@ -0,0 +1,10 @@
+/** A form's fields as a request body: URL-encoded, or multipart when there are files or the form asks for it. */
+export type EncodedForm = { body: string; contentType: string } | { body: FormData; contentType: null };
+
+export function encodeForm(data: FormData, multipart = false): EncodedForm {
+  const entries = [...data.entries()];
+  if (multipart || entries.some(([, value]) => typeof value !== 'string')) return { body: data, contentType: null };
+  const params = new URLSearchParams();
+  for (const [name, value] of entries) params.append(name, String(value));
+  return { body: params.toString(), contentType: 'application/x-www-form-urlencoded;charset=UTF-8' };
+}

package/src/form.tsx

@@ -0,0 +1,122 @@
+import type { ButtonHTMLAttributes, FormHTMLAttributes, SubmitEvent } from 'react';
+import { RETURN_FIELD, actionMetaOf } from './actions.tsx';
+import { encodeForm } from './form-data.ts';
+import type { Href } from './href.ts';
+import { useBasePath, useInternalRouter, usePagePayload, withBasePath } from './router.tsx';
+
+/** A React form action, e.g. the `formAction` from `useAction(serverAction('name'))`. */
+export type FormAction = (formData: FormData) => void | Promise<void>;
+
+/** The props of `<Form>`: a form's own, with client navigation and server action support. */
+export type FormProps = Omit<FormHTMLAttributes<HTMLFormElement>, 'method' | 'action'> & {
+  method?: 'get' | 'post';
+  /**
+   * Where to submit. Default: the current URL, which is where `MapPageAction` handlers for this page listen. Or a
+   * form action function: a server action from `useAction` (a real form post without JavaScript), or any function.
+   */
+  action?: string | FormAction;
+  replace?: boolean;
+  /**
+   * Let the browser submit it the classic way, with a full page load: for responses that are not pages, such as
+   * large file downloads, which the browser then streams to disk instead of Netjes buffering them.
+   */
+  reloadDocument?: boolean;
+};
+
+function formDataOf(form: HTMLFormElement, submitter: HTMLElement | null): FormData {
+  try {
+    return new FormData(form, submitter);
+  } catch {
+    const data = new FormData(form);
+    if (submitter instanceof HTMLButtonElement && submitter.name) data.append(submitter.name, submitter.value);
+    return data;
+  }
+}
+
+/**
+ * A `<form>` that submits without a full page load and handles the page action's result like a navigation:
+ * a redirect is followed, re-rendered props replace the page. Without JavaScript it is a normal form post.
+ * POST forms include the antiforgery token when the server has antiforgery enabled.
+ *
+ * With a function `action` React runs it (so `useFormStatus` works). For server actions the server renders a real
+ * `action`/`method`, the token and the return URL, so the same form also posts without JavaScript.
+ */
+export function Form({ method = 'get', action, replace = false, reloadDocument = false, onSubmit, children, ...rest }: FormProps) {
+  const router = useInternalRouter();
+  const payload = usePagePayload();
+  const basePath = useBasePath();
+  const isFunction = typeof action === 'function';
+  const serverAction = actionMetaOf(action);
+  const actionUrl = typeof action === 'string' ? withBasePath(action, basePath) : undefined;
+  const token = method === 'post' || serverAction ? payload.antiforgery : undefined;
+  const hidden = (
+    <>
+      {token?.requestToken && <input type="hidden" name={token.formFieldName} value={token.requestToken} />}
+      {serverAction && <input type="hidden" name={RETURN_FIELD} value={payload.url} />}
+    </>
+  );
+
+  if (isFunction) {
+    // React renders function actions as an inert placeholder on the server; a server action gets its real URL
+    // there instead. React keeps the server's attributes when hydrating a function action.
+    const onServer = typeof document === 'undefined';
+    return (
+      <form
+        {...rest}
+        action={onServer && serverAction ? withBasePath(serverAction.url, basePath) : action}
+        method={onServer && serverAction ? 'post' : undefined}
+        onSubmit={onSubmit}
+      >
+        {hidden}
+        {children}
+      </form>
+    );
+  }
+
+  function handleSubmit(event: SubmitEvent<HTMLFormElement>) {
+    onSubmit?.(event);
+    if (event.defaultPrevented || reloadDocument) return;
+    const form = event.currentTarget;
+    const submitter = event.submitter;
+    const target = submitter?.getAttribute('formtarget') ?? form.getAttribute('target');
+    if (target && target !== '_self') return;
+    const formAction = submitter?.getAttribute('formaction');
+    const url = new URL(formAction ? withBasePath(formAction, basePath) : (actionUrl ?? window.location.href), window.location.href);
+    if (url.origin !== window.location.origin) return;
+    event.preventDefault();
+
+    const data = formDataOf(form, submitter);
+    const submitMethod = (submitter?.getAttribute('formmethod') ?? method).toLowerCase();
+    if (submitMethod === 'post') {
+      void router.submit(url, encodeForm(data, form.enctype === 'multipart/form-data'));
+      return;
+    }
+    const query = new URLSearchParams();
+    for (const [name, value] of data.entries()) if (typeof value === 'string') query.append(name, value);
+    url.search = query.toString();
+    url.hash = '';
+    // Built from the form's own action, which is not one of the app's typed routes.
+    const href = url.href as Href;
+    void (replace ? router.replace(href) : router.push(href));
+  }
+
+  return (
+    <form method={method} action={actionUrl} {...rest} onSubmit={handleSubmit}>
+      {hidden}
+      {children}
+    </form>
+  );
+}
+
+/** The props of `<SubmitButton>`: a button's own, except `type`. */
+export type SubmitButtonProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'type'>;
+
+/**
+ * A submit button whose `formAction` is rendered under the base path, so it posts to the right place with and
+ * without JavaScript (a plain `<button formAction="/x">` would miss the base without JavaScript).
+ */
+export function SubmitButton({ formAction, ...rest }: SubmitButtonProps) {
+  const basePath = useBasePath();
+  const action = typeof formAction === 'string' ? withBasePath(formAction, basePath) : formAction;
+  return <button type="submit" formAction={action} {...rest} />;
+}

package/src/href.ts

@@ -0,0 +1,79 @@
+/**
+ * Apps register their generated route type here (the file `netjes generate` writes does it), which types the
+ * `href` of `<Link>` and `router.push`: `declare module 'netjes' { interface Register { href: Href } }`.
+ */
+// Empty on purpose: filled in by declaration merging.
+export interface Register {}
+
+/** A URL `<Link>` and the router accept: the app's routes once registered, any string before that. */
+export type Href = Register extends { href: infer H extends string } ? H : string;
+
+/** One value of a query string: `null` and `undefined` leave the key out. */
+export type SearchValue = string | number | boolean | null | undefined;
+/** A query string as an object: a value per key, or a list of values for a key that repeats. */
+export type SearchParamsInput = Record<string, SearchValue | readonly SearchValue[]>;
+
+function matches(pattern: readonly string[], path: readonly string[]): boolean {
+  for (let i = 0; i < pattern.length; i++) {
+    const segment = pattern[i]!;
+    if (segment.startsWith('[[...')) return true;
+    if (segment.startsWith('[...')) return path.length > i;
+    if (i >= path.length) return false;
+    if (!segment.startsWith('[') && segment !== path[i]) return false;
+  }
+  return pattern.length === path.length;
+}
+
+/**
+ * Whether a URL is one of the app's pages (by route pattern), a link within the page (`?…`, `#…`), or another
+ * site. The generated `isHref()` and `Href` schema call this to check URLs that come from data.
+ */
+export function isRouteHref(value: string, patterns: readonly string[]): boolean {
+  if (/^(https?:|mailto:|tel:)/i.test(value) || value.startsWith('?') || value.startsWith('#')) return true;
+  // "//host" and "/\host" are other hosts as far as browsers are concerned.
+  if (!value.startsWith('/') || value.startsWith('//') || value.startsWith('/\\')) return false;
+  const path = (value.split(/[?#]/, 1)[0] ?? '').split('/').filter(Boolean);
+  return patterns.some((pattern) => matches(pattern.split('/').filter(Boolean), path));
+}
+
+/**
+ * Builds the URL for a route pattern written in file-name syntax (`/blog/[slug]`, `/docs/[...path]`,
+ * `/shop/[[...filters]]`), encoding every segment value. The generated `route()` helper calls this with typed params.
+ */
+export function buildHref(pattern: string, params: Record<string, unknown>, search?: SearchParamsInput): string {
+  const missing = (name: string): never => {
+    throw new Error(`netjes: route '${pattern}' needs the parameter '${name}'`);
+  };
+  const segments = pattern
+    .split('/')
+    .filter(Boolean)
+    .flatMap((segment): string[] => {
+      const optional = /^\[\[\.\.\.(\w+)\]\]$/.exec(segment)?.[1];
+      if (optional) {
+        const values = params[optional];
+        return Array.isArray(values) ? values.map((v) => encodeURIComponent(String(v))) : [];
+      }
+      const catchAll = /^\[\.\.\.(\w+)\]$/.exec(segment)?.[1];
+      if (catchAll) {
+        const values = params[catchAll];
+        if (!Array.isArray(values) || values.length === 0) return missing(catchAll);
+        return values.map((v) => encodeURIComponent(String(v)));
+      }
+      const single = /^\[(\w+)\]$/.exec(segment)?.[1];
+      if (single) {
+        const value = params[single];
+        if (value === undefined || value === null || value === '') return missing(single);
+        return [encodeURIComponent(String(value))];
+      }
+      return [segment];
+    });
+
+  const query = new URLSearchParams();
+  for (const [key, value] of Object.entries(search ?? {})) {
+    for (const item of Array.isArray(value) ? value : [value]) {
+      if (item !== undefined && item !== null) query.append(key, String(item));
+    }
+  }
+  const queryString = query.toString();
+  return `/${segments.join('/')}${queryString ? `?${queryString}` : ''}`;
+}

package/src/image.tsx

@@ -0,0 +1,91 @@
+import { type ImgHTMLAttributes, createContext, useContext } from 'react';
+import { preload } from 'react-dom';
+
+/**
+ * Where the optimizer lives, and the widths and qualities it serves: Netjes:Images on the server, sent with the first
+ * document. Without `qualities`, any quality is requested as given.
+ */
+export type ImageConfig = { path: string; widths: readonly number[]; qualities?: readonly number[]; basePath?: string };
+
+/** Next.js's device and image sizes; the server's Netjes:Images:Widths default to the same. */
+const DEFAULT_CONFIG: ImageConfig = {
+  path: '/_netjes/image',
+  widths: [16, 32, 48, 64, 96, 128, 256, 384, 640, 750, 828, 1080, 1200, 1920, 2048, 3840],
+};
+
+const ImageConfigContext = createContext<ImageConfig>(DEFAULT_CONFIG);
+
+export const ImageConfigProvider = ImageConfigContext.Provider;
+
+/** The props of `<Image>`: an `<img>`'s own, with a required size and `alt`, and the optimizer's options. */
+export type ImageProps = Omit<ImgHTMLAttributes<HTMLImageElement>, 'src' | 'srcSet' | 'width' | 'height' | 'loading' | 'alt'> & {
+  /** A path in `public/` (`/img/hero.png`) or a URL on a host in Netjes:Images:RemoteHosts. */
+  src: string;
+  /** Required, as for any image; `""` for decorative ones. */
+  alt: string;
+  /** The intrinsic size in CSS pixels; reserves space so the page does not shift as it loads. */
+  width: number;
+  height: number;
+  /** For responsive layouts, e.g. `(max-width: 768px) 100vw, 50vw`: the browser then picks from every width. */
+  sizes?: string;
+  /** 1–100. Default 75. Rounded to the nearest of Netjes:Images:Qualities. */
+  quality?: number;
+  /** Above the fold: load eagerly with high priority, and preload it from the document head. */
+  priority?: boolean;
+  /** Serve `src` as is. SVGs and data URLs always are. */
+  unoptimized?: boolean;
+};
+
+function optimizerUrl(config: ImageConfig, src: string, width: number, quality: number) {
+  return `${config.path}?url=${encodeURIComponent(src)}&w=${width}&q=${quality}`;
+}
+
+/** The accepted quality nearest to the one asked for (the higher one on a tie). */
+function qualityFor(qualities: readonly number[] | undefined, wanted: number) {
+  if (!qualities?.length) return wanted;
+  return qualities.reduce((best, q) => (Math.abs(q - wanted) < Math.abs(best - wanted) || (Math.abs(q - wanted) === Math.abs(best - wanted) && q > best) ? q : best));
+}
+
+/** The smallest configured width that covers `target`, or the largest there is. */
+function widthFor(widths: readonly number[], target: number) {
+  return widths.find((w) => w >= target) ?? widths[widths.length - 1] ?? target;
+}
+
+function underBasePath(src: string, basePath: string | undefined) {
+  return basePath && src.startsWith('/') && !src.startsWith('//') && !src.startsWith(`${basePath}/`) ? basePath + src : src;
+}
+
+function isUnoptimizable(src: string) {
+  return src.startsWith('data:') || src.startsWith('blob:') || /\.svg($|[?#])/i.test(src);
+}
+
+/**
+ * Like `next/image`: an `<img>` with width and height (no layout shift), lazy loading, and a `srcset` of resized
+ * copies from the `/_netjes/image` endpoint, so each screen downloads only what it needs.
+ */
+export function Image({ src, alt, width, height, sizes, quality = 75, priority = false, unoptimized = false, ...rest }: ImageProps) {
+  const config = useContext(ImageConfigContext);
+  const common = {
+    ...rest,
+    alt,
+    width,
+    height,
+    decoding: 'async' as const,
+    loading: priority ? ('eager' as const) : ('lazy' as const),
+    ...(priority ? { fetchPriority: 'high' as const } : {}),
+  };
+  // Served as is, from public/: under the app's base path. (The optimizer's `url` stays a public/ path.)
+  if (unoptimized || isUnoptimizable(src)) return <img {...common} src={underBasePath(src, config.basePath)} />;
+
+  const widths = [...config.widths].sort((a, b) => a - b);
+  const q = qualityFor(config.qualities, quality);
+  // Responsive: every width, the browser picks by `sizes`. Fixed: 1x and 2x, each once.
+  const chosen = sizes ? widths : [...new Set([widthFor(widths, width), widthFor(widths, width * 2)])];
+  const srcSet = chosen
+    .map((w, i) => `${optimizerUrl(config, src, w, q)} ${sizes ? `${w}w` : `${i + 1}x`}`)
+    .join(', ');
+  const fallback = optimizerUrl(config, src, chosen[chosen.length - 1] ?? width, q);
+  if (priority) preload(fallback, { as: 'image', imageSrcSet: srcSet, ...(sizes ? { imageSizes: sizes } : {}), fetchPriority: 'high' });
+
+  return <img {...common} sizes={sizes} srcSet={srcSet} src={fallback} />;
+}

package/src/index.ts

@@ -0,0 +1,40 @@
+export {
+  type ActionState,
+  type PageActionFailure,
+  type ServerAction,
+  ServerActionError,
+  type UseActionOptions,
+  serverAction,
+  useAction,
+  usePageActionState,
+} from './actions.tsx';
+export { defineLayout, definePage } from './define-page.tsx';
+export { useDraftMode } from './draft-mode.ts';
+export { type DynamicOptions, clientOnly, dynamic } from './dynamic.tsx';
+export { Form, type FormAction, type FormProps, SubmitButton, type SubmitButtonProps } from './form.tsx';
+export { type Href, type Register, type SearchParamsInput, type SearchValue, buildHref, isRouteHref } from './href.ts';
+export { Image, type ImageProps } from './image.tsx';
+export { Link, type LinkProps } from './link.tsx';
+export { useLocale } from './locale.ts';
+export type { ErrorPageProps, LayoutProps } from './modules.ts';
+export { useNonce } from './nonce.tsx';
+export type { PageKind, Params, SeededQuery, SegmentRef } from './payload.ts';
+export { usePublicConfig } from './public-config.tsx';
+export { Script, type ScriptProps, type ScriptStrategy } from './script.tsx';
+export {
+  type NavigationState,
+  type SubmitError,
+  type Router,
+  useBasePath,
+  useHref,
+  useNavigation,
+  useParams,
+  usePathname,
+  useRouter,
+  useSearchParams,
+  useSelectedLayoutSegment,
+  useSelectedLayoutSegments,
+  useSharedProps,
+} from './router.tsx';
+export type { StandardSchemaV1 } from './schema.ts';
+export type { Metadata, MetadataImage, MetadataTitle } from './metadata.tsx';

package/src/link.tsx

@@ -0,0 +1,73 @@
+import type { AnchorHTMLAttributes, MouseEvent } from 'react';
+import type { Href } from './href.ts';
+import { useBasePath, useInternalRouter, usePathname, withBasePath } from './router.tsx';
+
+/** The props of `<Link>`: an anchor's own, with a typed `href` and the client navigation options. */
+export type LinkProps = Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> & {
+  /** Typed by the app's routes once `netjes generate` has registered them. */
+  href: Href;
+  replace?: boolean;
+  /** Scroll to the top (or the #fragment) after navigating. Default true. */
+  scroll?: boolean;
+  /** `intent` (default) fetches the next page on hover or focus. */
+  prefetch?: 'intent' | 'none';
+  /** Let the browser follow it with a full page load, e.g. for a file download or a page outside Netjes. */
+  reloadDocument?: boolean;
+};
+
+const BASE = 'http://netjes.invalid';
+
+function isCurrentPath(href: string, pathname: string) {
+  const url = new URL(href, BASE + pathname);
+  return url.origin === BASE && url.pathname === pathname;
+}
+
+function isPlainLeftClick(event: MouseEvent<HTMLAnchorElement>) {
+  const anchor = event.currentTarget;
+  return (
+    event.button === 0 &&
+    !event.metaKey &&
+    !event.ctrlKey &&
+    !event.shiftKey &&
+    !event.altKey &&
+    (!anchor.target || anchor.target === '_self') &&
+    !anchor.hasAttribute('download')
+  );
+}
+
+/** An `<a>` that navigates on the client. Ctrl/cmd-click, new tabs and external URLs behave like a normal link. */
+export function Link({ href, replace = false, scroll = true, prefetch = 'intent', reloadDocument = false, onClick, onMouseEnter, onFocus, onTouchStart, ...rest }: LinkProps) {
+  const router = useInternalRouter();
+  const pathname = usePathname();
+  const basePath = useBasePath();
+  const warm = () => {
+    if (prefetch === 'intent' && !reloadDocument) router.prefetch(href);
+  };
+
+  return (
+    <a
+      href={withBasePath(href, basePath)}
+      aria-current={isCurrentPath(href, pathname) ? 'page' : undefined}
+      {...rest}
+      onClick={(event) => {
+        onClick?.(event);
+        if (event.defaultPrevented || reloadDocument || !isPlainLeftClick(event)) return;
+        if (new URL(href, window.location.href).origin !== window.location.origin) return;
+        event.preventDefault();
+        void (replace ? router.replace(href, { scroll }) : router.push(href, { scroll }));
+      }}
+      onMouseEnter={(event) => {
+        onMouseEnter?.(event);
+        warm();
+      }}
+      onFocus={(event) => {
+        onFocus?.(event);
+        warm();
+      }}
+      onTouchStart={(event) => {
+        onTouchStart?.(event);
+        warm();
+      }}
+    />
+  );
+}

package/src/locale.ts

@@ -0,0 +1,6 @@
+import { usePagePayload } from './router.tsx';
+
+/** The request culture the server rendered this page in (`AddNetjesLocalization`), e.g. `nl`; null without localization. */
+export function useLocale(): string | null {
+  return usePagePayload().locale ?? null;
+}