Ported inventions, part 1: forms, validation, persistence, docs scaffold

.config/mise/conf.d/_config.toml

@@ -5,7 +5,7 @@ min_version = "2026.4.18" # required for [deps] (renamed from [prepare])
 node = "lts"
 jq = "latest"
 vp = "latest"
-hk = "latest"
+hk = "1" # hk 2 cannot evaluate a config that amends the 1.x Config.pkl
 
 [task_config]
 dir = "{{ config_root }}"

apps/demo/messages/en/articles.json

@@ -15,7 +15,6 @@
 	"article_search_placeholder": "Search articles...",
 	"article_loading_detail": "Loading article detail",
 	"article_saving": "Saving…",
-	"article_saved": "Article saved",
 	"article_save_error": "Couldn't save the article. Try again.",
 	"article_cancel": "Cancel",
 	"article_save": "Save",

apps/demo/messages/en/auth.json

@@ -3,6 +3,9 @@
 	"login_description": "Use your workspace credentials to continue.",
 	"login_email": "Email",
 	"login_password": "Password",
+	"login_email_required": "Email is required",
+	"login_email_invalid": "Email doesn't look right",
+	"login_password_required": "Password is required",
 	"login_submit": "Sign in",
 	"login_signing_in": "Signing in",
 	"login_error_title": "Could not sign in",

apps/demo/messages/en/settings.json

@@ -42,7 +42,5 @@
 	"settings_error_title": "Could not load settings",
 	"settings_error_description": "We couldn't load your settings. Try again in a moment.",
 	"settings_saving": "Saving…",
-	"settings_profile_saved": "Profile saved",
-	"settings_notifications_saved": "Notification preferences saved",
 	"settings_save_error": "Couldn't save. Try again."
 }

apps/demo/messages/es/articles.json

@@ -15,7 +15,6 @@
 	"article_search_placeholder": "Buscar artículos...",
 	"article_loading_detail": "Cargando detalle del artículo",
 	"article_saving": "Guardando…",
-	"article_saved": "Artículo guardado",
 	"article_save_error": "No se pudo guardar el artículo. Inténtalo de nuevo.",
 	"article_cancel": "Cancelar",
 	"article_save": "Guardar",

apps/demo/messages/es/auth.json

@@ -3,6 +3,9 @@
 	"login_description": "Usa tus credenciales del espacio de trabajo para continuar.",
 	"login_email": "Correo electrónico",
 	"login_password": "Contraseña",
+	"login_email_required": "El correo electrónico es obligatorio",
+	"login_email_invalid": "El correo no parece válido",
+	"login_password_required": "La contraseña es obligatoria",
 	"login_submit": "Iniciar sesión",
 	"login_signing_in": "Iniciando sesión",
 	"login_error_title": "No se pudo iniciar sesión",

apps/demo/messages/es/settings.json

@@ -42,7 +42,5 @@
 	"settings_error_title": "No se pudieron cargar los ajustes",
 	"settings_error_description": "No pudimos cargar tus ajustes. Inténtalo de nuevo en un momento.",
 	"settings_saving": "Guardando…",
-	"settings_profile_saved": "Perfil guardado",
-	"settings_notifications_saved": "Preferencias de notificaciones guardadas",
 	"settings_save_error": "No se pudo guardar. Inténtalo de nuevo."
 }

apps/demo/src/app/integration/Articles.detail.stories.tsx

@@ -174,7 +174,7 @@ EditArticle.test('saving updates the title and returns to read mode', async () =
 		await I.openEdit()
 		await I.fill(role('textbox', 'Title'), 'Updated quarterly report')
 		await I.saveArticle()
-		await I.seeArticleSavedToast()
+		await I.seeArticleSaved()
 		await I.see(button('Edit'))
 		await I.see(heading('Updated quarterly report'))
 	})
@@ -185,11 +185,9 @@ EditArticle.test('changing status persists and reflects on return', async () =>
 		await I.openEdit()
 		await I.selectOption(role('combobox'), 'In Progress')
 		await I.saveArticle()
-		await I.seeArticleSavedToast()
-		// A prior save test in this story leaves a stale "Article saved" toast
-		// in the global toaster, so `seeArticleSavedToast` can resolve against it
-		// before this save transitions to read mode. Wait for the real transition.
-		await I.retryTo(() => I.see(button('Edit')), 25)
+		// The edit panel collapsing to the summary rows is what confirms the
+		// save — there is no toast to observe.
+		await I.seeArticleSaved()
 		await I.seeArticleDetailStatus('In Progress')
 	})
 })
@@ -204,13 +202,13 @@ export const EditArticleServerError = meta.story({
 })
 
 EditArticleServerError.test(
-	'save failure shows an error toast and stays in edit mode',
+	'save failure shows an inline alert and stays in edit mode',
 	async () => {
 		await I.scope(role('main'), async () => {
 			await I.openEdit()
 			await I.fill(role('textbox', 'Title'), 'Will not save')
 			await I.saveArticle()
-			await I.seeArticleSaveErrorToast()
+			await I.seeArticleSaveError()
 			await I.see(role('textbox', 'Title'))
 		})
 	},

apps/demo/src/app/integration/Settings.stories.tsx

@@ -92,8 +92,7 @@ EditProfileShowsSave.test('save button disappears after saving', async () => {
 	await I.fill(role('textbox', 'Display name'), 'Jane Doe')
 	await I.see(button('Save changes'))
 	await I.saveProfile()
-	await I.seeProfileSavedToast()
-	await I.dontSee(button('Save changes'))
+	await I.savedProfileClearsDirty(loc.profileForm)
 })
 
 export const ToggleSwitches = meta.story({ name: 'Toggle Switches', play: waitForLoad })
@@ -246,12 +245,11 @@ RetrySuccess.test('loads settings after retry succeeds', async () => {
 
 export const SaveProfileSuccess = meta.story({ name: 'Save Profile', play: waitForLoad })
 
-SaveProfileSuccess.test('saving profile shows success toast and clears dirty', async () => {
+SaveProfileSuccess.test('saving profile clears dirty and keeps the saved values', async () => {
 	await I.fill(role('textbox', 'Display name'), 'Jane Doe')
 	await I.see(button('Save changes'))
 	await I.saveProfile()
-	await I.seeProfileSavedToast()
-	await I.dontSee(button('Save changes'))
+	await I.savedProfileClearsDirty(loc.profileForm)
 	await I.seeInField(role('textbox', 'Display name'), 'Jane Doe')
 })
 
@@ -260,16 +258,12 @@ export const SaveNotificationsSuccess = meta.story({
 	play: waitForLoad,
 })
 
-SaveNotificationsSuccess.test(
-	'saving notifications shows success toast and clears dirty',
-	async () => {
-		await I.selectOption(role('combobox', 'Email notifications'), 'Important only')
-		await I.see(button('Save changes'))
-		await I.saveNotifications()
-		await I.seeNotificationsSavedToast()
-		await I.dontSee(button('Save changes'))
-	},
-)
+SaveNotificationsSuccess.test('saving notifications clears dirty', async () => {
+	await I.selectOption(role('combobox', 'Email notifications'), 'Important only')
+	await I.see(button('Save changes'))
+	await I.saveNotifications()
+	await I.savedProfileClearsDirty(loc.notificationsForm)
+})
 
 export const SaveProfileError = meta.story({
 	name: 'Save Profile Error',
@@ -280,9 +274,9 @@ export const SaveProfileError = meta.story({
 	},
 })
 
-SaveProfileError.test('save server error shows error toast and keeps dirty', async () => {
+SaveProfileError.test('save server error shows an inline alert and keeps dirty', async () => {
 	await I.fill(role('textbox', 'Display name'), 'Jane Doe')
 	await I.saveProfile()
-	await I.seeSaveErrorToast()
+	await I.seeSaveError(loc.profileForm)
 	await I.see(button('Save changes'))
 })

apps/demo/src/entities/auth/mocks/handlers.ts

@@ -2,7 +2,7 @@ import { HttpResponse, delay, http } from 'msw'
 
 import { AUTH_LOGIN_API_PATH, AUTH_LOGOUT_API_PATH } from '#entities/auth/api/authApi'
 import { composeApiUrl } from '#shared/api'
-import { to400, to500 } from '#shared/mocks/utils'
+import { to400, to422, to500 } from '#shared/mocks/utils'
 
 import { authMockSession } from './data'
 
@@ -13,6 +13,12 @@ export const authHandlers = {
 	login: http.post(loginUrl, async ({ request }) => {
 		await delay()
 		const body = (await request.json()) as { email?: string; password?: string }
+		// A server-side uniqueness check is the one credential rule the client
+		// cannot pre-validate — it demonstrates a validation error that maps
+		// onto a form field.
+		if (body.email === 'taken@example.com') {
+			to422([{ loc: ['body', 'email'], msg: 'This email is already registered' }])
+		}
 		if (body.email !== authMockSession.user.email || body.password !== 'password') {
 			return to400('Invalid email or password')
 		}

apps/demo/src/entities/setting/index.ts

@@ -1,8 +1,2 @@
 export { fetchSettings, updateNotifications, updateProfile } from './api/settingsApi'
-export type {
-	DesktopNotification,
-	EmailNotification,
-	NotificationSettings,
-	ProfileSettings,
-	SettingsData,
-} from './model/types'
+export type { DesktopNotification, EmailNotification, SettingsData } from './model/types'

apps/demo/src/pages/articles/model/articleDetailModel.test.ts

@@ -0,0 +1,67 @@
+import type { Article } from '#entities/article'
+
+import { context } from '@reatom/core'
+import { afterEach, expect, test, vi } from 'vite-plus/test'
+
+import { updateArticle } from '#entities/article'
+
+import { reatomArticleDetailModel } from './articleDetailModel'
+
+vi.mock('#entities/article', () => ({ updateArticle: vi.fn() }))
+
+afterEach(() => {
+	context.reset()
+	vi.mocked(updateArticle).mockReset()
+})
+
+// `submit.onFulfill` hooks run in the next cleanup-queue tick.
+const flush = () => new Promise<void>((resolve) => setTimeout(resolve, 0))
+
+const article: Article = {
+	id: 'a1',
+	title: 'Original',
+	description: 'Description',
+	status: 'draft',
+	content: [],
+}
+
+const respondWith = (release: Promise<void>) =>
+	vi.mocked(updateArticle).mockImplementation(async (id, values) => {
+		await release
+		return { id, ...values }
+	})
+
+test('a save with nothing typed during the request closes edit mode', async () => {
+	respondWith(Promise.resolve())
+	const model = reatomArticleDetailModel(article)
+	model.startEdit()
+
+	model.form.fields.title.change('Saved')
+	await model.form.submit()
+	await flush()
+
+	expect(model.current().title).toBe('Saved')
+	expect(model.isEditing()).toBe(false)
+})
+
+test('an edit typed while the save is in flight keeps edit mode open', async () => {
+	let release: (() => void) | undefined
+	respondWith(
+		new Promise<void>((resolve) => {
+			release = resolve
+		}),
+	)
+	const model = reatomArticleDetailModel(article)
+	model.startEdit()
+
+	model.form.fields.title.change('Sent')
+	const submitted = model.form.submit()
+	model.form.fields.title.change('Typed during save')
+	release?.()
+	await submitted
+	await flush()
+
+	expect(model.current().title).toBe('Sent')
+	expect(model.form.fields.title.value()).toBe('Typed during save')
+	expect(model.isEditing()).toBe(true)
+})

apps/demo/src/pages/articles/model/articleDetailModel.ts

@@ -1,38 +1,9 @@
 import type { Article } from '#entities/article'
 
-import {
-	abortVar,
-	action,
-	atom,
-	framePromise,
-	reatomForm,
-	sleep,
-	withAbort,
-	withAsync,
-	wrap,
-} from '@reatom/core'
+import { abortVar, action, atom, reatomForm, wrap } from '@reatom/core'
 
 import { updateArticle } from '#entities/article'
-import { m } from '#paraglide/messages.js'
-import { toaster } from '#shared/components'
-
-const SAVE_DELAY_MS = 300
-
-async function saveWithToast(articleId: string, values: Omit<Article, 'id'>) {
-	const id = toaster.create({ title: m.article_saving(), type: 'loading', closable: false })
-	void framePromise().catch(() => {})
-	try {
-		const updated = await wrap(
-			updateArticle(articleId, values, { signal: abortVar.require().signal }),
-		)
-		await wrap(sleep(SAVE_DELAY_MS))
-		toaster.update(id, { title: m.article_saved(), type: 'success' })
-		return updated
-	} catch (error) {
-		toaster.remove(id)
-		throw error
-	}
-}
+import { withSavedState } from '#shared/reatom'
 
 export function reatomArticleDetailModel(article: Article) {
 	const id = article.id
@@ -48,8 +19,27 @@ export function reatomArticleDetailModel(article: Article) {
 		},
 		{
 			name: `article.${id}.editForm`,
-			onSubmit: async (values) => await wrap(saveWithToast(id, values)),
+			onSubmit: async (values) => {
+				const updated = await wrap(updateArticle(id, values, { signal: abortVar.require().signal }))
+				// The summary rows move when the request lands; withSavedState then
+				// rebaselines the form and its onSaved collapses back to them —
+				// seeing the new values on the rows is what confirms the save.
+				current.set(updated)
+				// withSavedState rebaselines through form.init, whose keys must be
+				// field names exactly: returning the full Article (with `id`) would
+				// throw `Field id not found in fields`.
+				const { id: _, ...fields } = updated
+				return fields
+			},
 		},
+	).extend((target) =>
+		withSavedState({
+			// An edit typed while the request was in flight keeps the form dirty;
+			// collapsing would hide it behind rows showing the saved values.
+			onSaved: () => {
+				if (!target.focus().dirty) isEditing.set(false)
+			},
+		})(target),
 	)
 
 	const startEdit = action(() => {
@@ -62,24 +52,7 @@ export function reatomArticleDetailModel(article: Article) {
 		isEditing.set(true)
 	}, `article.${id}.startEdit`)
 
-	const save = action(async () => {
-		if (!form.focus().dirty) return
-		try {
-			const updated = await wrap(form.submit())
-			current.set(updated)
-			form.init({
-				title: updated.title,
-				description: updated.description,
-				status: updated.status,
-				content: updated.content,
-			})
-			isEditing.set(false)
-		} catch {
-			toaster.create({ title: m.article_save_error(), type: 'error' })
-		}
-	}, `article.${id}.save`).extend(withAbort(), withAsync())
-
-	return { id, current, isEditing, form, startEdit, save }
+	return { id, current, isEditing, form, startEdit }
 }
 
 export type ArticleDetailModel = ReturnType<typeof reatomArticleDetailModel>

apps/demo/src/pages/articles/testing.ts

@@ -20,6 +20,7 @@ const ARTICLE_LINKS = [
 ] as const
 
 const editLoc = {
+	editForm: role('form', m.article_detail()),
 	editButton: button('Edit'),
 	saveButton: button('Save'),
 	cancelButton: button('Cancel'),
@@ -130,17 +131,13 @@ export const articlesActor = createActor()
 		saveArticle: async () => {
 			await I.click(editLoc.saveButton)
 		},
-		seeArticleSavedToast: async () => {
-			// Require the current save's loading toast before accepting success, so a
-			// stale global success toast from another story/test cannot satisfy this helper.
-			await I.retryTo(() => I.see(role('status', 'Saving…').within('global')), 25)
-			await I.retryTo(() => I.see(role('status', 'Article saved').within('global')), 25)
-		},
-		seeArticleSaveErrorToast: async () => {
-			await I.retryTo(
-				() => I.see(text("Couldn't save the article. Try again.").within('global')),
-				25,
-			)
+		// A save is confirmed by the state change itself: the edit panel collapses
+		// to the summary rows, which now state the saved values — there is no toast.
+		seeArticleSaved: async () => {
+			await I.retryTo(() => I.see(editLoc.editButton), 25)
+		},
+		seeArticleSaveError: async () => {
+			await I.retryTo(() => I.see(role('alert').within(editLoc.editForm)), 25)
 		},
 		seeTitleIs: async (value: string) => {
 			await I.retryTo(() => I.seeInField(editLoc.titleField, value), 25)