@riducms/admin 0.2.2 → 0.3.0

package/src/core/forms/plugin-field-write.ts

@@ -1,6 +1,6 @@
 import type { SchemaField } from "@riducms/protocol";
 import type { FormController } from "@admin/core/forms/form-controller.svelte";
-import { indexFieldValues } from "@admin/core/forms/form-issue-correlation";
+import { canRebaseIndexedSuffix, indexFieldValues } from "@admin/core/forms/form-issue-correlation";
 import { fieldAccessPath } from "@admin/fields/nested/scoped-field";
 import { evaluateFieldCondition } from "@admin/core/forms/field-condition";
 
@@ -43,11 +43,7 @@ export function writePluginField(form: FormController, field: SchemaField, value
 			const target = current.get(source.token);
 			if (!target) continue;
 			const suffix = path.slice(source.path.length);
-			if (
-				/\.\d+(?:\.|$)/.test(suffix) &&
-				JSON.stringify(source.value) !== JSON.stringify(target.value)
-			)
-				continue;
+			if (!canRebaseIndexedSuffix(suffix, source.value, target.value)) continue;
 			fields[target.path + suffix] = access;
 		}
 		form.access = { ...form.access, fields };

package/src/core/i18n/admin-i18n.svelte.ts

@@ -214,6 +214,24 @@ export class AdminI18nController implements AdminI18n {
 		this.#applyDocumentLanguage();
 	}
 
+	adoptPreparedPreferences(language: string | undefined, timeZone: string | undefined) {
+		this.#preferenceRequest += 1;
+		this.#languageWrite += 1;
+		this.#timeZoneWrite += 1;
+		if (language !== undefined && this.languages.some((item) => item.code === language)) {
+			this.#language = language;
+			this.#confirmedLanguage = language;
+			writeBrowserPreference(browserLanguageKey, language);
+		}
+		if (timeZone !== undefined && this.timeZones.some((item) => item.id === timeZone)) {
+			this.#timeZone = timeZone;
+			this.#confirmedTimeZone = timeZone;
+			writeBrowserPreference(browserTimeZoneKey, timeZone);
+		}
+		this.#invalidateTranslator();
+		this.#applyDocumentLanguage();
+	}
+
 	async setLanguage(language: string) {
 		if (!this.languages.some((item) => item.code === language)) {
 			throw new Error(`Admin language ${language} is not configured.`);

package/src/core/i18n/format-admin-date-time.ts

@@ -0,0 +1,19 @@
+import type { AdminI18n } from "@riducms/translations";
+
+export function formatAdminDateTime(value: string, i18n: AdminI18n) {
+	const date = new Date(value);
+	if (!Number.isFinite(date.valueOf())) return value;
+	if (i18n.language.startsWith("en")) {
+		const day = Number(i18n.formatDate(date, { day: "numeric" }));
+		const suffix =
+			day % 100 >= 11 && day % 100 <= 13 ? "th" : ({ 1: "st", 2: "nd", 3: "rd" }[day % 10] ?? "th");
+		return `${i18n.formatDate(date, { month: "long" })} ${day}${suffix} ${i18n.formatDate(date, { year: "numeric" })}, ${i18n.formatDate(date, { hour: "numeric", minute: "2-digit" })}`;
+	}
+	return i18n.formatDate(date, {
+		year: "numeric",
+		month: "long",
+		day: "numeric",
+		hour: "numeric",
+		minute: "2-digit",
+	});
+}

package/src/core/i18n/humanize-identifier.ts

@@ -0,0 +1,5 @@
+export function humanizeIdentifier(value: string, language: string) {
+	return value
+		.replaceAll(/[_-]+/g, " ")
+		.replace(/\b\w/g, (letter) => letter.toLocaleUpperCase(language));
+}

package/src/core/i18n/time-zone-label.ts

@@ -0,0 +1,20 @@
+/** Describe a configured timezone using its offset and localized name at the displayed instant. */
+export function timeZoneLabel(id: string, label: string, language: string, at: Date) {
+	const fixedOffset = /^[+-]\d{2}:\d{2}$/.test(id);
+	const offset = new Intl.DateTimeFormat("en", {
+		timeZone: id,
+		timeZoneName: "longOffset",
+	})
+		.formatToParts(at)
+		.find((part) => part.type === "timeZoneName")!.value;
+	const name = new Intl.DateTimeFormat(language, {
+		timeZone: id,
+		timeZoneName: "long",
+	})
+		.formatToParts(at)
+		.find((part) => part.type === "timeZoneName")!.value;
+	const utcOffset = offset === "GMT" ? "UTC+00:00" : offset.replace("GMT", "UTC");
+	const description =
+		fixedOffset || name === label || name === offset ? label : `${label} (${name})`;
+	return `(${utcOffset}) ${description}`;
+}

package/src/core/loaders/admin-view-host.svelte

@@ -0,0 +1,72 @@
+<script lang="ts" generics="Props extends object">
+	import type { AdminViewComponent } from "@riducms/plugin";
+	import { useLocation } from "@hvniel/svelte-router";
+	import { getAdminRuntime } from "@admin/core/runtime/admin-runtime.svelte";
+	import { getAdminBootstrapCoordinator } from "@admin/core/bootstrap/admin-bootstrap";
+	import { normalizedURLIdentity } from "@admin/core/bootstrap/admin-prepared-state";
+	import { Banner } from "@admin/components/ui/banner";
+	import { Button } from "@riducms/ui";
+	import { AdminViewLoader } from "@admin/core/loaders/admin-view-loader.svelte";
+	import { registerAdminScrollPage } from "@admin/core/routing/admin-scroll.svelte";
+
+	let {
+		view,
+		props,
+		ownsRoute = false,
+	}: { view: AdminViewComponent<Props>; props: Props; ownsRoute?: boolean } = $props();
+	const runtime = getAdminRuntime();
+	const bootstrap = getAdminBootstrapCoordinator();
+	const location = useLocation();
+	// Registrations are static for the lifetime of this keyed host.
+	// svelte-ignore state_referenced_locally
+	const loader = view.loader;
+	const controller =
+		loader === undefined
+			? undefined
+			: new AdminViewLoader({
+					client: runtime.client,
+					loader,
+					get route() {
+						return normalizedURLIdentity(location.current);
+					},
+					get prepared() {
+						return bootstrap.loaderData(
+							loader.key,
+							location.current.pathname,
+							location.current.search
+						);
+					},
+				});
+	// Route hosts wait for their fallback read or terminal error before restoring scroll. Dashboard
+	// panels share a page and deliberately leave this false so they cannot compete for ownership.
+	// svelte-ignore state_referenced_locally
+	const routeOwner = ownsRoute;
+	if (routeOwner) {
+		registerAdminScrollPage({
+			ready: () => loader === undefined || controller?.settled === true,
+		});
+	}
+</script>
+
+{#if view.loader === undefined}
+	<view.component {...props} />
+{:else if controller !== undefined}
+	{#if controller.error !== undefined}
+		<Banner tone="destructive">
+			<p>{controller.error}</p>
+			<Button variant="outline" onclick={controller.refresh}>
+				{runtime.i18n.t("general:retry")}
+			</Button>
+		</Banner>
+	{/if}
+	{#if controller.ready}
+		<view.component
+			{...props}
+			data={controller.data}
+			refresh={controller.refresh}
+			refreshing={controller.refreshing}
+		/>
+	{:else if controller.error === undefined}
+		<div aria-busy="true" data-ridu-loading-surface="admin-view-loader"></div>
+	{/if}
+{/if}

package/src/core/loaders/admin-view-loader.svelte.ts

@@ -0,0 +1,90 @@
+import { RiduError, type AdminLoader } from "@riducms/sdk";
+import type { AdminReadResultV1 } from "@riducms/protocol";
+import type { AdminClient } from "@admin/core/api/admin-client";
+
+interface AdminViewLoaderOptions {
+	client: Pick<AdminClient, "adminLoad">;
+	loader: AdminLoader<never, unknown>;
+	get route(): string;
+	get prepared(): AdminReadResultV1<unknown> | undefined;
+}
+
+/** One mounted view owns its data and supersedable refresh. */
+export class AdminViewLoader {
+	#data = $state.raw<unknown>();
+	#ready = $state(false);
+	#refreshing = $state(false);
+	#error = $state<string>();
+	#request?: AbortController;
+	#route?: string;
+
+	constructor(private readonly options: AdminViewLoaderOptions) {
+		// Adopt router data before a retained panel can render the destination query.
+		$effect.pre(() => {
+			const route = options.route;
+			if (route === this.#route) return;
+			this.#route = route;
+			this.#request?.abort();
+			this.#request = undefined;
+			this.#ready = false;
+			this.#refreshing = false;
+			this.#error = undefined;
+			const prepared = options.prepared;
+			if (prepared !== undefined) {
+				if (prepared.error !== undefined) this.#error = prepared.error.message;
+				else {
+					this.#data = options.loader.decode(prepared.value);
+					this.#ready = true;
+				}
+			} else this.refresh();
+		});
+		$effect(() => () => this.#request?.abort());
+	}
+
+	get data() {
+		return this.#data;
+	}
+
+	get ready() {
+		return this.#ready;
+	}
+
+	get refreshing() {
+		return this.#refreshing;
+	}
+
+	get error() {
+		return this.#error;
+	}
+
+	get settled() {
+		return this.#ready || this.#error !== undefined;
+	}
+
+	refresh = async () => {
+		const route = this.options.route;
+		this.#request?.abort();
+		const request = new AbortController();
+		this.#request = request;
+		this.#refreshing = true;
+		this.#error = undefined;
+		try {
+			const data = await this.options.client.adminLoad(this.options.loader.key, route, {
+				signal: request.signal,
+			});
+			// Aborting cannot undo a response that already completed; only the current owner may
+			// decode and publish it.
+			if (request.signal.aborted) return;
+			this.#data = this.options.loader.decode(data);
+			this.#ready = true;
+		} catch (cause) {
+			if (request.signal.aborted) return;
+			this.#error = cause instanceof RiduError ? cause.message : "Unable to load view data.";
+		} finally {
+			if (this.#request === request) {
+				this.#request = undefined;
+				this.#refreshing = false;
+			}
+		}
+	};
+}

package/src/core/notifications/validation-toast.svelte

@@ -9,9 +9,9 @@
 {:else}
 	<div>
 		<p>The following fields are invalid ({labels.length}):</p>
-		<ul class="mt-1 list-[circle] space-y-0.5 ps-5">
+		<ul class="ridu-validation-toast__fields">
 			{#each labels as label (label)}
-				<li class="ps-0.5">{label}</li>
+				<li>{label}</li>
 			{/each}
 		</ul>
 	</div>

package/src/core/plugins/field-registry.ts

@@ -1,22 +1,22 @@
 import { type ResolvedPluginField } from "@riducms/plugin";
 import type { FieldType, SchemaField } from "@riducms/protocol";
 
-interface FieldRenderer {
+interface FieldEditorRegistration {
 	type: FieldType;
 	extension?: ResolvedPluginField;
 }
 export class FieldRegistry {
-	#plugins = new Map<string, FieldRenderer>();
+	#plugins = new Map<string, FieldEditorRegistration>();
 	register(plugin: ResolvedPluginField) {
 		const identity =
 			plugin.componentKey === undefined
 				? `plugin:${plugin.key}`
 				: `${plugin.registration.type}:${plugin.owner}:${plugin.key}`;
 		if (this.#plugins.has(identity))
-			throw new Error(`Field renderer ${identity} is already registered.`);
+			throw new Error(`Field editor ${identity} is already registered.`);
 		this.#plugins.set(identity, { type: plugin.registration.type, extension: plugin });
 	}
-	resolve(field: SchemaField): FieldRenderer {
+	resolve(field: SchemaField): FieldEditorRegistration {
 		if (field.admin.editor !== undefined)
 			throw new Error(
 				`No local editor ${field.admin.editor.reference} is registered for ${field.path}.`
@@ -27,10 +27,9 @@ export class FieldRegistry {
 			component === undefined
 				? `plugin:${field.plugin?.key}`
 				: `${field.type}:${component.plugin}:${component.component}`;
-		const renderer = this.#plugins.get(identity);
-		if (!renderer)
-			throw new Error(`No admin field renderer can render ${field.path} (${identity}).`);
-		return renderer;
+		const editor = this.#plugins.get(identity);
+		if (!editor) throw new Error(`No admin field editor can render ${field.path} (${identity}).`);
+		return editor;
 	}
 }
 export function createCoreFieldRegistry(

package/src/core/routing/admin-paths.ts

@@ -23,6 +23,50 @@ export const adminRoutePatterns = {
 	globalVersion: "/globals/:global/versions/:revision",
 } as const;
 
+export function adminPathSegments(pathname: string): string[] {
+	return pathname
+		.split("/")
+		.filter(Boolean)
+		.map((segment) => {
+			try {
+				return decodeURIComponent(segment);
+			} catch {
+				return segment;
+			}
+		});
+}
+
+export function parseAdminVersionRevision(value: string | undefined): number | undefined {
+	const revision = Number(value);
+	return Number.isSafeInteger(revision) && revision > 0 ? revision : undefined;
+}
+
+export function humanizeAdminPathSegment(value: string, language: string): string {
+	const words = value.replaceAll(/[-_]+/g, " ");
+	return words.charAt(0).toLocaleUpperCase(language) + words.slice(1);
+}
+
+export function adminLayoutRouteBehavior(pathname: string): {
+	ownsViewport: boolean;
+	waitsForPage: boolean;
+} {
+	const segments = adminPathSegments(pathname);
+	const collectionDocument =
+		segments[0] === "collections" &&
+		segments.length > 2 &&
+		segments[2] !== "trash" &&
+		segments[2] !== "upload" &&
+		segments[3] !== "versions";
+	const globalDocument =
+		segments[0] === "globals" && segments.length > 1 && segments[2] !== "versions";
+	const ownsViewport = collectionDocument || globalDocument;
+	const collectionPage =
+		segments[0] === "collections" &&
+		(segments.length === 2 || (segments.length === 3 && segments[2] === "trash"));
+
+	return { ownsViewport, waitsForPage: ownsViewport || collectionPage };
+}
+
 const adminAuthPaths = new Set<string>([
 	adminRoutePatterns.login,
 	adminRoutePatterns.createFirstUser,
@@ -52,7 +96,8 @@ function safeAdminRedirectPath(requestedPath: string | null | undefined): string
 		requestedPath === null ||
 		requestedPath === undefined ||
 		!requestedPath.startsWith("/") ||
-		requestedPath.startsWith("//")
+		requestedPath.startsWith("//") ||
+		requestedPath.includes("\\")
 	) {
 		return adminRoutePatterns.home;
 	}
@@ -92,16 +137,22 @@ export function collectionUploadPath(collection: string): string {
 	return `${collectionPath(collection)}/upload`;
 }
 
+export function withContentLocale(path: string, locale: string | undefined): string {
+	if (locale === undefined) return path;
+	return `${path}?${new URLSearchParams({ locale }).toString()}`;
+}
+
 export function documentPath(collection: string, document: string): string {
 	return `${collectionPath(collection)}/${encodeURIComponent(document)}`;
 }
 
 export function documentIDFromAdminPath(pathname: string): string | undefined {
 	const segments = pathname.split("/");
-	if (segments[1] !== "collections" || segments[3] === undefined || segments[3] === "") {
+	if (segments[1] === undefined || segments[3] === undefined || segments[3] === "") {
 		return undefined;
 	}
 	try {
+		if (decodeURIComponent(segments[1]).toLowerCase() !== "collections") return undefined;
 		return decodeURIComponent(segments[3]);
 	} catch {
 		return undefined;

package/src/core/routing/admin-scroll.svelte.ts

@@ -0,0 +1,74 @@
+import { useHref, useLocation, useScrollRestoration } from "@hvniel/svelte-router";
+import { createContext, tick } from "svelte";
+import { SvelteMap } from "svelte/reactivity";
+
+interface AdminScrollPage {
+	ready: () => boolean;
+	target?: () => HTMLElement | null;
+}
+
+const [getAdminScroll, setAdminScroll] = createContext<{
+	readonly page: AdminScrollPage | undefined;
+	register: (page: AdminScrollPage) => () => void;
+}>();
+
+/** Provide before route definitions so every retained/replaced route inherits one identity. */
+export function createAdminScroll() {
+	// A keyed mutation lets outgoing cleanup remove only its own entry. Replacing
+	// a rune array from teardown can overwrite registrations made in the incoming batch.
+	const pages = new SvelteMap<symbol, AdminScrollPage>();
+	setAdminScroll({
+		get page() {
+			return Array.from(pages.values()).at(-1);
+		},
+		register(next) {
+			const owner = Symbol();
+			pages.set(owner, next);
+			return () => {
+				pages.delete(owner);
+			};
+		},
+	});
+}
+
+/** The shell owns restoration; a route supplies its content readiness and optional primary pane. */
+export function useAdminScrollRestoration(
+	target: () => Window | HTMLElement | null,
+	waitForPage: () => boolean
+) {
+	const location = useLocation();
+	const root = useHref("/");
+	const scroll = getAdminScroll();
+	const page = $derived(scroll.page);
+	let renderedLocation = $state.raw<ReturnType<typeof useLocation>["current"]>();
+
+	$effect(() => {
+		const current = location.current;
+		const ready = page?.ready() ?? !waitForPage();
+		renderedLocation = undefined;
+		let active = true;
+		// Controllers synchronize the new URL in effects. Wait for those effects and
+		// their DOM flush before accepting readiness left over from the outgoing page.
+		tick().then(() => {
+			if (active && ready) renderedLocation = current;
+		});
+		return () => {
+			active = false;
+		};
+	});
+
+	useScrollRestoration({
+		storageKey: `ridu-admin-scroll:${root.current}`,
+		target: () => {
+			const shell = target();
+			return shell === window || page?.target === undefined ? shell : page.target();
+		},
+		ready: () => renderedLocation === location.current && (page?.ready() ?? !waitForPage()),
+	});
+}
+
+export function registerAdminScrollPage(page: AdminScrollPage) {
+	const scroll = getAdminScroll();
+	// Register before the shell's restoration effect; release only this route's ownership.
+	$effect.pre(() => scroll.register(page));
+}

package/src/core/routing/admin-view-selection.ts

@@ -0,0 +1,78 @@
+import type { AdminCoreView, AdminCoreViewSurface } from "@riducms/plugin";
+import type { ResolvedAdminConfig } from "@riducms/plugin/admin";
+import type { SchemaManifest } from "@riducms/protocol";
+import { matchRoutes } from "@hvniel/svelte-router";
+import { adminRoutePatterns } from "@admin/core/routing/admin-paths";
+
+/** Select the registration first: an un-loaded exact replacement suppresses a wildcard loader. */
+export function resolveCoreView(
+	coreViews: readonly AdminCoreView[],
+	surface: AdminCoreViewSurface,
+	resource?: string
+) {
+	const candidates = coreViews.filter((view) => view.surface === surface);
+	const target = (view: AdminCoreView) =>
+		view.surface === "global"
+			? view.global
+			: view.surface === "notFound"
+				? undefined
+				: view.collection;
+	return (
+		candidates.find((view) => target(view) === resource) ??
+		candidates.find((view) => target(view) === undefined)
+	);
+}
+
+const replacementSurfaces: Partial<Record<keyof typeof adminRoutePatterns, AdminCoreViewSurface>> =
+	{
+		collection: "collectionList",
+		createDocument: "collectionCreate",
+		createDocumentAPI: "collectionCreate",
+		document: "collectionEdit",
+		documentAPI: "collectionEdit",
+		global: "global",
+		globalAPI: "global",
+	};
+
+/** Use the router's ranking/decoding, including more-specific document tabs and reserved paths. */
+export function preparedCustomView(
+	config: ResolvedAdminConfig,
+	pathname: string,
+	manifest?: SchemaManifest
+) {
+	const routes = [
+		...Object.entries(adminRoutePatterns).map(([key, path]) => ({
+			path,
+			surface: replacementSurfaces[key as keyof typeof adminRoutePatterns],
+			view: undefined,
+		})),
+		...config.extensions.routes.map((view) => ({ path: view.path, surface: undefined, view })),
+		...config.extensions.documentViews.flatMap((view) => [
+			{
+				path: `collections/${view.collection ?? ":collection"}/:document/${view.key}`,
+				surface: undefined,
+				view: undefined,
+			},
+			{
+				path: `globals/${view.collection ?? ":global"}/${view.key}`,
+				surface: undefined,
+				view: undefined,
+			},
+		]),
+		{ path: "*", surface: "notFound" as const, view: undefined },
+	];
+	const match = matchRoutes(routes, pathname)?.[0];
+	if (match?.route.view !== undefined) return match.route.view;
+	const surface = match?.route.surface;
+	if (surface === undefined) return undefined;
+	const resource = surface === "global" ? match?.params.global : match?.params.collection;
+	if (
+		manifest !== undefined &&
+		surface !== "notFound" &&
+		!(surface === "global" ? manifest.globals : manifest.collections)?.some(
+			(item) => item.slug === resource
+		)
+	)
+		return undefined;
+	return resolveCoreView(config.extensions.coreViews, surface, resource);
+}