alepha 0.21.2 → 0.23.0

package/dist/react/router/index.browser.js

@@ -2,7 +2,7 @@ import { $atom, $hook, $inject, $module, $state, Alepha, AlephaError, KIND, OPTI
 import { AlephaDateTime, DateTimeProvider } from "alepha/datetime";
 import { AlephaContext, AlephaReact, ClientOnly, ErrorBoundary, useAlepha, useEvents, useInject, useStore } from "alepha/react";
 import { AlephaReactHead, BrowserHeadProvider } from "alepha/react/head";
-import { AlephaServer, ForbiddenError } from "alepha/server";
+import { AlephaServer } from "alepha/server";
 import { AlephaServerLinks, LinkProvider } from "alepha/server/links";
 import { $cache } from "alepha/cache";
 import { $logger } from "alepha/logger";
@@ -719,6 +719,117 @@ function parseAnimation(animationLike, state, type = "enter") {
 	}
 }
 //#endregion
+//#region ../../src/react/router/providers/RootComponentsProvider.ts
+/**
+* Extension point letting any module contribute root-level React nodes that
+* render on every page (siblings of the page view, inside AlephaContext).
+*
+* A module pushes into `rootComponents` from its `register` hook; the array
+* is rendered by `ReactPageProvider.root()`. SSR-safe (same element feeds
+* server render + client hydrate).
+*/
+var RootComponentsProvider = class {
+	rootComponents = [];
+};
+//#endregion
+//#region ../../src/react/router/providers/RouterLocaleProvider.ts
+/**
+* Generic locale path-prefix mechanism for the router.
+*
+* This provider knows nothing about i18n — it only deals with URL path
+* segments. It is configured by the i18n module (`I18nProvider`) when
+* `routing: "prefix"` is enabled, which keeps the dependency one-directional
+* (`i18n → router`) and avoids a module cycle.
+*
+* The default locale is served WITHOUT a prefix (`/about` = default,
+* `/fr/about` = French). The active locale is derived from the current
+* request/navigation and stored under `alepha.react.router.locale`, so every
+* URL the router builds (`pathname()`) automatically carries the right prefix.
+*/
+var RouterLocaleProvider = class {
+	alepha = $inject(Alepha);
+	/**
+	* Whether locale path-prefixing is active. Off by default — opt-in via the
+	* i18n module.
+	*/
+	enabled = false;
+	/**
+	* The default locale, served without a path prefix (e.g. `"en"` → `/about`).
+	*/
+	defaultLocale = "";
+	/**
+	* All known locales, including the default one.
+	*/
+	locales = [];
+	/**
+	* Configure the provider. Called by the i18n module before the SSR routes
+	* are registered.
+	*/
+	configure(options) {
+		if (options.enabled !== void 0) this.enabled = options.enabled;
+		if (options.defaultLocale !== void 0) this.defaultLocale = options.defaultLocale;
+		if (options.locales !== void 0) this.locales = options.locales;
+	}
+	/**
+	* Locales that carry a URL prefix — every known locale except the default.
+	*/
+	get prefixedLocales() {
+		return this.locales.filter((locale) => locale !== this.defaultLocale);
+	}
+	/**
+	* Splits a leading locale segment off a pathname.
+	*
+	* - `/fr/about` → `{ locale: "fr", pathname: "/about" }` when `fr` is a
+	*   prefixed locale.
+	* - `/about` → `{ locale: defaultLocale, pathname: "/about" }`.
+	*
+	* When prefixing is disabled the pathname is returned untouched.
+	*/
+	detect(pathname) {
+		if (this.enabled) {
+			const first = pathname.split("/")[1];
+			if (first && this.prefixedLocales.includes(first)) {
+				const rest = pathname.slice(first.length + 1);
+				return {
+					locale: first,
+					pathname: this.normalize(rest)
+				};
+			}
+		}
+		return {
+			locale: this.defaultLocale,
+			pathname
+		};
+	}
+	/**
+	* Prepends the locale prefix to a pathname when needed. The default locale
+	* (and any unknown/disabled case) returns the pathname unchanged.
+	*/
+	withPrefix(pathname, locale = this.current) {
+		if (!this.enabled || !locale || locale === this.defaultLocale || !this.prefixedLocales.includes(locale)) return pathname;
+		return `/${locale}${pathname === "/" ? "" : pathname}`;
+	}
+	/**
+	* The active locale, derived from the current request/navigation. Falls back
+	* to the default locale when nothing has been detected.
+	*/
+	get current() {
+		return this.alepha.store.get("alepha.react.router.locale") || this.defaultLocale;
+	}
+	set current(locale) {
+		this.alepha.store.set("alepha.react.router.locale", locale);
+	}
+	/**
+	* Normalizes a stripped pathname so it always starts with a single slash and
+	* carries no trailing slash (except the root `/`).
+	*/
+	normalize(pathname) {
+		if (!pathname || pathname === "/") return "/";
+		const withLeading = pathname.startsWith("/") ? pathname : `/${pathname}`;
+		return withLeading.length > 1 && withLeading.endsWith("/") ? withLeading.slice(0, -1) : withLeading;
+	}
+};
+//#endregion
 //#region ../../src/react/router/providers/ReactPageProvider.ts
 const reactPageOptions = $atom({
 	name: "alepha.react.page.options",
@@ -752,6 +863,8 @@ var ReactPageProvider = class {
 	log = $logger();
 	options = $state(reactPageOptions);
 	alepha = $inject(Alepha);
+	rootComponentsProvider = $inject(RootComponentsProvider);
+	localeProvider = $inject(RouterLocaleProvider);
 	pages = [];
 	nextIdCursor = 0;
 	configure = $hook({
@@ -834,17 +947,19 @@ var ReactPageProvider = class {
 			parent = parent.parent;
 		}
 		url = this.compile(url, options.params ?? {});
+		url = url.replace(/\/\/+/g, "/") || "/";
+		url = this.localeProvider.withPrefix(url);
 		if (options.query) {
 			const query = new URLSearchParams(options.query);
 			if (query.toString()) url += `?${query.toString()}`;
 		}
-		return url.replace(/\/\/+/g, "/") || "/";
+		return url;
 	}
 	url(name, options = {}) {
 		return new URL(this.pathname(name, options), options.host ?? `http://localhost`);
 	}
 	root(state) {
-		const root = createElement(AlephaContext.Provider, { value: this.alepha }, createElement(NestedView_default, {}, state.layers[0]?.element));
+		const root = createElement(AlephaContext.Provider, { value: this.alepha }, createElement(NestedView_default, {}, state.layers[0]?.element), ...this.rootComponentsProvider.rootComponents);
 		if (this.options.strictMode) return createElement(StrictMode, {}, root);
 		return root;
 	}
@@ -1162,6 +1277,7 @@ var ReactBrowserRouterProvider = class extends RouterProvider {
 	alepha = $inject(Alepha);
 	pageApi = $inject(ReactPageProvider);
 	browserHeadProvider = $inject(BrowserHeadProvider);
+	localeProvider = $inject(RouterLocaleProvider);
 	add(entry) {
 		this.pageApi.add(entry);
 	}
@@ -1190,12 +1306,15 @@ var ReactBrowserRouterProvider = class extends RouterProvider {
 			state
 		});
 		try {
-			const { route, params } = this.match(pathname);
+			let matchPathname = pathname;
+			if (this.localeProvider.enabled) {
+				const detected = this.localeProvider.detect(pathname);
+				this.localeProvider.current = detected.locale;
+				matchPathname = detected.pathname;
+			}
+			const { route, params } = this.match(matchPathname);
 			const query = {};
 			if (search) for (const [key, value] of new URLSearchParams(search).entries()) query[key] = String(value);
-			if (route?.page.can) {
-				if (!route.page.can()) throw new ForbiddenError("Access denied to this page.");
-			}
 			state.name = route?.page.name;
 			state.query = query;
 			state.params = params ?? {};
@@ -1735,36 +1854,85 @@ const useActive = (args) => {
 //#region ../../src/react/router/hooks/useQueryParams.ts
 /**
 * Hook to manage query parameters in the URL using a defined schema.
+*
+* Two storage formats are supported via {@link UseQueryParamsHookOptions.format}:
+* - `"base64"` (default) packs the whole object into a single opaque param
+*   (named by `key`, default `q`) — e.g. `?q=eyJ0YWIiOiJzZWN1cml0eSJ9`.
+* - `"querystring"` spreads each schema field across its own readable param —
+*   e.g. `?tab=security`. In this mode `key` is ignored.
+*
+* By default the URL is updated with `replaceState` (no new history entry).
+* Pass `push: true` to add a history entry instead, so the browser back
+* button steps back through previous values.
+*
+* @example
+* const [params, setParams] = useQueryParams(
+*   t.object({ tab: t.optional(t.string()) }),
+*   { format: "querystring" },
+* );
+* // params.tab reads from `?tab=…`; setParams({ tab: "security" }) writes it.
 */
 const useQueryParams = (schema, options = {}) => {
 	const alepha = useAlepha();
-	const key = options.key ?? "q";
 	const router = useRouter();
-	const querystring = router.query[key];
-	const [queryParams = {}, setQueryParams] = useState(decode(alepha, schema, router.query[key]));
+	const key = options.key ?? "q";
+	const format = options.format ?? "base64";
+	const read = () => format === "querystring" ? decodeQueryString(alepha, schema, router.query) : decodeBase64(alepha, schema, router.query[key]);
+	const signature = format === "querystring" ? Object.keys(schema.properties).map((name) => `${name}=${router.query[name] ?? ""}`).join("&") : router.query[key];
+	const [queryParams = {}, setQueryParams] = useState(read());
 	useEffect(() => {
-		setQueryParams(decode(alepha, schema, querystring));
-	}, [querystring]);
-	return [queryParams, (queryParams) => {
-		setQueryParams(queryParams);
-		router.setQueryParams((data) => {
-			return {
-				...data,
-				[key]: encode(alepha, schema, queryParams)
-			};
-		});
+		setQueryParams(read());
+	}, [signature]);
+	return [queryParams, (next) => {
+		setQueryParams(next);
+		router.setQueryParams((data) => format === "querystring" ? writeQueryString(alepha, schema, data, next) : {
+			...data,
+			[key]: encodeBase64(alepha, schema, next)
+		}, { push: options.push });
 	}];
 };
-const encode = (alepha, schema, data) => {
+const encodeBase64 = (alepha, schema, data) => {
 	return btoa(JSON.stringify(alepha.codec.decode(schema, data)));
 };
-const decode = (alepha, schema, data) => {
+const decodeBase64 = (alepha, schema, data) => {
 	try {
 		return alepha.codec.decode(schema, JSON.parse(atob(decodeURIComponent(data))));
 	} catch {
 		return;
 	}
 };
+/**
+* querystring read: each schema field is its own URL param. Mirrors the
+* server's per-key query decode — `codec.decode(propertySchema, rawString)`
+* coerces the raw string into the declared type (number, boolean, …).
+*/
+const decodeQueryString = (alepha, schema, query) => {
+	try {
+		const out = {};
+		for (const name of Object.keys(schema.properties)) {
+			const raw = query[name];
+			if (raw != null && raw !== "") out[name] = alepha.codec.decode(schema.properties[name], raw);
+		}
+		return out;
+	} catch {
+		return;
+	}
+};
+/**
+* querystring write: spread the decoded object across individual params,
+* dropping empty values so the URL stays clean. Unrelated params (not part
+* of the schema) are preserved.
+*/
+const writeQueryString = (alepha, schema, current, next) => {
+	const decoded = alepha.codec.decode(schema, next);
+	const merged = { ...current };
+	for (const name of Object.keys(schema.properties)) {
+		const value = decoded?.[name];
+		if (value == null || value === "") delete merged[name];
+		else merged[name] = String(value);
+	}
+	return merged;
+};
 //#endregion
 //#region ../../src/react/router/index.browser.ts
 const AlephaReactRouter = $module({
@@ -1776,11 +1944,12 @@ const AlephaReactRouter = $module({
 		ReactBrowserProvider,
 		ReactRouter,
 		ReactBrowserRendererProvider,
+		RouterLocaleProvider,
 		ReactPageService
 	],
-	register: (alepha) => alepha.with(AlephaReact).with(AlephaReactHead).with(AlephaDateTime).with(AlephaServer).with(AlephaServerLinks).with(ReactPageProvider).with(ReactBrowserProvider).with(ReactBrowserRouterProvider).with(ReactBrowserRendererProvider).with(ReactRouter)
+	register: (alepha) => alepha.with(AlephaReact).with(AlephaReactHead).with(AlephaDateTime).with(AlephaServer).with(AlephaServerLinks).with(ReactPageProvider).with(ReactBrowserProvider).with(ReactBrowserRouterProvider).with(ReactBrowserRendererProvider).with(RouterLocaleProvider).with(ReactRouter)
 });
 //#endregion
-export { $page, AlephaReactRouter, ErrorViewer, Link, NestedView_default as NestedView, NotFound, PAGE_PRELOAD_KEY, PagePrimitive, ReactBrowserProvider, ReactBrowserRendererProvider, ReactBrowserRouterProvider, ReactPageProvider, ReactPageService, ReactRouter, Redirection, RouterLayerContext, isPageRoute, reactBrowserOptions, reactPageOptions, useActive, useQueryParams, useRouter, useRouterState };
+export { $page, AlephaReactRouter, ErrorViewer, Link, NestedView_default as NestedView, NotFound, PAGE_PRELOAD_KEY, PagePrimitive, ReactBrowserProvider, ReactBrowserRendererProvider, ReactBrowserRouterProvider, ReactPageProvider, ReactPageService, ReactRouter, Redirection, RootComponentsProvider, RouterLayerContext, RouterLocaleProvider, isPageRoute, reactBrowserOptions, reactPageOptions, useActive, useQueryParams, useRouter, useRouterState };
 
 //# sourceMappingURL=index.browser.js.map