Product workflows

"use client"
 
import type {
	DeepReadonly,
	FieldPath,
	FormBinding,
	FormInput,
	StandardSchema,
} from "form-please"
import { nativeFormKit } from "form-please/preset-native"
import { useEffect, useMemo, useRef, useState } from "react"
import { type FieldValues, useWatch } from "react-hook-form"
import { z } from "zod"
 
export type WorkflowStep<
	Input extends FieldValues,
	Screen extends string,
> = Readonly<{
	/** Stable application screen identifier. */
	screen: Screen
	/** User-facing progress label. */
	label: string
	/** Schema input paths validated before this screen can be left. */
	paths: readonly FieldPath<Input>[]
	/** Includes the screen only while the current input satisfies this condition. */
	when?: (input: DeepReadonly<Input>) => boolean
}>
 
type WorkflowInput<Schema extends StandardSchema> = Extract<
	FormInput<Schema>,
	FieldValues
>
 
type UseFormWorkflowOptions<
	Schema extends StandardSchema,
	Context,
	Screen extends string,
> = Readonly<{
	form: FormBinding<Schema, Context>
	screen: Screen
	setScreen(screen: NoInfer<Screen>): void
	steps: readonly WorkflowStep<WorkflowInput<Schema>, Screen>[]
}>
 
/**
 * Application-owned workflow navigation over one Form Please binding.
 * The Standard Schema remains the only validation contract.
 */
export function useFormWorkflow<
	Schema extends StandardSchema,
	Context,
	Screen extends string,
>({
	form,
	screen,
	setScreen,
	steps,
}: UseFormWorkflowOptions<Schema, Context, Screen>) {
	type Input = WorkflowInput<Schema>
	type Path = FieldPath<Input>
 
	const input = useWatch({ control: form.api.control }) as Input
	const pendingFocus = useRef<Readonly<{
		path: Path
		screen: Screen
	}> | null>(null)
	const visibleSteps = steps.filter(
		(step) => step.when?.(input as DeepReadonly<Input>) ?? true,
	)
	const currentIndex = visibleSteps.findIndex((step) => step.screen === screen)
	const currentStep = visibleSteps[currentIndex]
 
	useEffect(() => {
		const pending = pendingFocus.current
		if (pending === null || pending.screen !== screen) return
		pendingFocus.current = null
		form.api.setFocus(pending.path)
	}, [form, screen])
 
	function focusInvalid(step: WorkflowStep<Input, Screen>, path: Path) {
		if (step.screen === screen) {
			form.api.setFocus(path)
			return
		}
		pendingFocus.current = { path, screen: step.screen }
		setScreen(step.screen)
	}
 
	function touch(paths: readonly Path[]) {
		for (const path of paths) {
			form.api.setValue(path, form.api.getValues(path), { shouldTouch: true })
		}
	}
 
	async function validateStep(
		step: WorkflowStep<Input, Screen>,
	): Promise<boolean> {
		if (step.paths.length === 0) return true
		touch(step.paths)
		const valid = await form.api.trigger([...step.paths])
		if (valid) return true
 
		const firstInvalid = step.paths.find(
			(path) => form.api.getFieldState(path).invalid,
		)
		if (firstInvalid !== undefined) focusInvalid(step, firstInvalid)
		return false
	}
 
	async function validateCurrent(): Promise<boolean> {
		if (currentStep === undefined) return false
		return validateStep(currentStep)
	}
 
	async function next(): Promise<boolean> {
		if (currentStep === undefined || !(await validateStep(currentStep))) {
			return false
		}
		const nextStep = visibleSteps[currentIndex + 1]
		if (nextStep === undefined) return false
		setScreen(nextStep.screen)
		return true
	}
 
	function back(): boolean {
		const previousStep = visibleSteps[currentIndex - 1]
		if (previousStep === undefined) return false
		setScreen(previousStep.screen)
		return true
	}
 
	async function validateAllAndFocusFirstInvalid(): Promise<boolean> {
		const paths = [...new Set(visibleSteps.flatMap((step) => step.paths))]
		if (paths.length === 0) return true
		touch(paths)
		const valid = await form.api.trigger(paths)
		if (valid) return true
 
		for (const step of visibleSteps) {
			const firstInvalid = step.paths.find(
				(path) => form.api.getFieldState(path).invalid,
			)
			if (firstInvalid !== undefined) {
				focusInvalid(step, firstInvalid)
				break
			}
		}
		return false
	}
 
	const total = visibleSteps.length
	let current = 0
	if (currentIndex >= 0) current = currentIndex + 1
	let percent = 0
	if (total > 0) percent = Math.round((current / total) * 100)
 
	return {
		back,
		currentStep,
		next,
		progress: {
			current,
			percent,
			total,
		},
		validateAllAndFocusFirstInvalid,
		validateCurrent,
		visibleSteps,
	} as const
}
 
const onboardingSchema = z
	.object({
		name: z.string().min(1, "Enter a name"),
		email: z.email("Enter a valid email"),
		organization: z.boolean(),
		organizationName: z.string(),
		department: z.string().min(1, "Enter a department"),
	})
	.superRefine((input, context) => {
		if (input.organization && input.organizationName.trim() === "") {
			context.addIssue({
				code: "custom",
				message: "Enter the organization name",
				path: ["organizationName"],
			})
		}
	})
 
type OnboardingInput = FormInput<typeof onboardingSchema>
type OnboardingScreen = "identity" | "organization" | "details" | "review"
type OnboardingContext = { readonly screen: OnboardingScreen }
 
const identityPaths = [
	"name",
	"email",
	"organization",
] as const satisfies readonly FieldPath<OnboardingInput>[]
const organizationPaths = [
	"organizationName",
] as const satisfies readonly FieldPath<OnboardingInput>[]
const detailPaths = [
	"department",
] as const satisfies readonly FieldPath<OnboardingInput>[]
 
const onboardingSteps = [
	{ screen: "identity", label: "Identity", paths: identityPaths },
	{
		screen: "organization",
		label: "Organization",
		paths: organizationPaths,
		when: (input) => input.organization,
	},
	{ screen: "details", label: "Details", paths: detailPaths },
	{ screen: "review", label: "Review", paths: [] },
] satisfies readonly WorkflowStep<OnboardingInput, OnboardingScreen>[]
 
const onboardingKit = nativeFormKit.forContext<OnboardingContext>()
const onboardingDefinition = onboardingKit.defineForm(onboardingSchema, {
	ui: [
		{
			kind: "field",
			path: "name",
			control: "text",
			label: "Name",
			visible: (_input, { context }) =>
				context.screen === "identity" || context.screen === "review",
		},
		{
			kind: "field",
			path: "email",
			control: "text",
			label: "Email",
			props: { type: "email" },
			visible: (_input, { context }) =>
				context.screen === "identity" || context.screen === "review",
		},
		{
			kind: "field",
			path: "organization",
			control: "checkbox",
			label: "I represent an organization",
			visible: (_input, { context }) =>
				context.screen === "identity" || context.screen === "review",
		},
		{
			kind: "field",
			path: "organizationName",
			control: "text",
			label: "Organization name",
			visible: (input, { context }) =>
				input.organization &&
				(context.screen === "organization" || context.screen === "review"),
		},
		{
			kind: "field",
			path: "department",
			control: "text",
			label: "Department",
			visible: (_input, { context }) =>
				context.screen === "details" || context.screen === "review",
		},
	],
})
 
export function ProductWorkflowRecipe() {
	const [screen, setScreen] = useState<OnboardingScreen>("identity")
	const [status, setStatus] = useState("Complete the current screen.")
	const context = useMemo(() => ({ screen }), [screen])
	const form = onboardingKit.useForm(onboardingDefinition, {
		context,
		defaultValues: {
			name: "",
			email: "",
			organization: true,
			organizationName: "",
			department: "",
		},
		readOnly: screen === "review",
		onSubmit: ({ value }) => {
			setStatus(`Published ${value.name}.`)
		},
	})
	const workflow = useFormWorkflow({
		form,
		screen,
		setScreen,
		steps: onboardingSteps,
	})
 
	let actions = (
		<button type="button" onClick={() => void workflow.next()}>
			Continue
		</button>
	)
	if (screen === "details") {
		actions = (
			<>
				<button type="button" onClick={() => form.api.setValue("name", "")}>
					Clear identity name
				</button>
				<button
					type="button"
					onClick={async () => {
						if (await workflow.validateAllAndFocusFirstInvalid()) {
							setScreen("review")
						}
					}}
				>
					Review
				</button>
			</>
		)
	}
	if (screen === "review") {
		actions = (
			<onboardingKit.Submit name="intent" value="publish">
				Publish
			</onboardingKit.Submit>
		)
	}
 
	return (
		<section
			aria-label="Product workflow recipe preview"
			className="form-please-complex"
		>
			<p className="form-please-complex__kicker">Product workflow</p>
			<p className="form-please-complex__summary">
				{workflow.currentStep?.label ?? "Unavailable screen"}. Step{" "}
				{workflow.progress.current} of {workflow.progress.total}.
			</p>
			<progress
				aria-label="Workflow progress"
				max={100}
				value={workflow.progress.percent}
			/>
			<onboardingKit.AutoForm form={form}>
				<div className="form-please-complex__actions">
					<button
						disabled={workflow.progress.current <= 1}
						type="button"
						onClick={() => workflow.back()}
					>
						Back
					</button>
					{actions}
				</div>
			</onboardingKit.AutoForm>
			<output aria-live="polite">{status}</output>
		</section>
	)
}

"use client"
 
import { nativeFormKit } from "form-please/preset-native"
import { useState } from "react"
import { z } from "zod"
 
const articleSchema = z.object({
	title: z.string().min(1, "Enter a title"),
	summary: z.string().min(20, "Write at least 20 characters"),
})
 
type ReviewScreen = "edit" | "review"
type PublishReceipt = Readonly<{ id: string; publishedTitle: string }>
 
const articleDefinition = nativeFormKit.defineForm(articleSchema, {
	ui: [
		{ kind: "field", path: "title", control: "text", label: "Title" },
		{
			kind: "field",
			path: "summary",
			control: "textarea",
			label: "Summary",
			props: { rows: 5 },
		},
	],
})
 
async function publishArticle(
	value: z.output<typeof articleSchema>,
): Promise<PublishReceipt> {
	return { id: "article-42", publishedTitle: value.title.trim() }
}
 
export function ArticleWorkflow() {
	const [screen, setScreen] = useState<ReviewScreen>("edit")
	const [receipt, setReceipt] = useState<PublishReceipt>()
	const form = nativeFormKit.useForm(articleDefinition, {
		defaultValues: { title: "", summary: "" },
		readOnly: screen === "review",
		onSubmit: async ({ value }) => {
			setReceipt(await publishArticle(value))
		},
	})
 
	if (receipt !== undefined) {
		return (
			<section aria-labelledby="confirmation-title">
				<h2 id="confirmation-title">Article published</h2>
				<p>Confirmation ID: {receipt.id}</p>
				<p>Published title: {receipt.publishedTitle}</p>
			</section>
		)
	}
	let actions = (
		<button type="button" onClick={() => setScreen("review")}>
			Review current input
		</button>
	)
	if (screen === "review") {
		actions = (
			<>
				<button type="button" onClick={() => setScreen("edit")}>
					Edit
				</button>
				<nativeFormKit.Submit name="intent" value="publish">
					Publish
				</nativeFormKit.Submit>
			</>
		)
	}
 
	return <nativeFormKit.AutoForm form={form}>{actions}</nativeFormKit.AutoForm>
}

npm install react-router

"use client"
 
import type { PersistenceHandle } from "form-please/persistence"
import { useCallback, useState } from "react"
import { useBeforeUnload, useBlocker } from "react-router"
 
type PersistedNavigationGuardProps = Readonly<{
	dirty: boolean
	persistence: PersistenceHandle
}>
 
/** Use inside a React Router data or framework router. */
export function PersistedNavigationGuard({
	dirty,
	persistence,
}: PersistedNavigationGuardProps) {
	const [error, setError] = useState<string>()
	const [saving, setSaving] = useState(false)
	const blocker = useBlocker(dirty)
 
	useBeforeUnload(
		useCallback(
			(event) => {
				if (!dirty) return
				event.preventDefault()
				event.returnValue = ""
			},
			[dirty],
		),
	)
 
	if (blocker.state !== "blocked") return null
 
	async function saveDraftAndLeave() {
		if (blocker.state !== "blocked") return
		const proceed = blocker.proceed
		setError(undefined)
		setSaving(true)
		try {
			await persistence.flush()
			proceed()
		} catch {
			setError("The draft could not be saved. Navigation is still blocked.")
			setSaving(false)
		}
	}
	let saveLabel = "Save draft and leave"
	if (saving) saveLabel = "Saving draft…"
 
	return (
		<div aria-labelledby="leave-title" role="dialog" aria-modal="true">
			<h2 id="leave-title">Leave this form?</h2>
			<p>
				Save the latest input before navigation, or leave without saving it.
			</p>
			{error !== undefined && <p role="alert">{error}</p>}
			<button disabled={saving} type="button" onClick={() => blocker.reset()}>
				Stay
			</button>
			<button disabled={saving} type="button" onClick={() => blocker.proceed()}>
				Leave without saving
			</button>
			<button
				disabled={saving}
				type="button"
				onClick={() => void saveDraftAndLeave()}
			>
				{saveLabel}
			</button>
		</div>
	)
}

"use client"
 
import type { FieldPath, FormBinding, FormInput } from "form-please"
import { nativeFormKit } from "form-please/preset-native"
import { useEffect, useMemo, useRef, useState } from "react"
import { z } from "zod"
 
const profileSchema = z.object({
	name: z.string().min(1),
	email: z.email(),
	department: z.string().min(1),
})
type ProfileInput = FormInput<typeof profileSchema>
type ProfileScreen = "identity" | "work"
type ProfileContext = { readonly screen: ProfileScreen }
type ProfileForm = FormBinding<typeof profileSchema, ProfileContext>
 
const serverIssueSchema = z.object({
	issues: z.array(
		z.object({
			path: z.enum([
				"profile.full_name",
				"profile.email_address",
				"employment.department",
			]),
			message: z.string(),
		}),
	),
})
type ServerIssue = z.output<typeof serverIssueSchema>["issues"][number]
 
const inputPathByServerPath = {
	"profile.full_name": "name",
	"profile.email_address": "email",
	"employment.department": "department",
} satisfies Record<ServerIssue["path"], FieldPath<ProfileInput>>
 
const screenByInputPath = {
	name: "identity",
	email: "identity",
	department: "work",
} satisfies Record<FieldPath<ProfileInput>, ProfileScreen>
 
function applyServerIssues(
	form: ProfileForm,
	issues: readonly ServerIssue[],
): FieldPath<ProfileInput> | undefined {
	form.api.clearErrors(Object.values(inputPathByServerPath))
	let firstPath: FieldPath<ProfileInput> | undefined
 
	for (const issue of issues) {
		const path = inputPathByServerPath[issue.path]
		firstPath ??= path
		form.api.setError(path, { message: issue.message, type: "server" })
	}
	return firstPath
}
 
const profileKit = nativeFormKit.forContext<ProfileContext>()
const profileDefinition = profileKit.defineForm(profileSchema, {
	ui: [
		{
			kind: "field",
			path: "name",
			control: "text",
			label: "Name",
			visible: (_input, { context }) => context.screen === "identity",
		},
		{
			kind: "field",
			path: "email",
			control: "text",
			label: "Email",
			props: { type: "email" },
			visible: (_input, { context }) => context.screen === "identity",
		},
		{
			kind: "field",
			path: "department",
			control: "text",
			label: "Department",
			visible: (_input, { context }) => context.screen === "work",
		},
	],
})
 
export function ServerValidatedProfile() {
	const [screen, setScreen] = useState<ProfileScreen>("identity")
	const [requestError, setRequestError] = useState<string>()
	const pendingFocus = useRef<Readonly<{
		path: FieldPath<ProfileInput>
		screen: ProfileScreen
	}> | null>(null)
	const context = useMemo(() => ({ screen }), [screen])
	const form = profileKit.useForm(profileDefinition, {
		context,
		defaultValues: { name: "", email: "", department: "" },
		onSubmit: async ({ form, value }) => {
			setRequestError(undefined)
			try {
				const response = await fetch("/api/profile", {
					method: "POST",
					headers: { "content-type": "application/json" },
					body: JSON.stringify(value),
				})
				const body: unknown = await response.json()
				const result = serverIssueSchema.parse(body)
				const firstPath = applyServerIssues(form, result.issues)
				if (firstPath === undefined) return
				const issueScreen = screenByInputPath[firstPath]
				if (issueScreen === screen) {
					form.api.setFocus(firstPath)
					return
				}
				pendingFocus.current = { path: firstPath, screen: issueScreen }
				setScreen(issueScreen)
			} catch {
				setRequestError("The profile could not be saved.")
			}
		},
	})
	useEffect(() => {
		const pending = pendingFocus.current
		if (pending === null || pending.screen !== screen) return
		pendingFocus.current = null
		form.api.setFocus(pending.path)
	}, [form, screen])
 
	return (
		<profileKit.AutoForm form={form} data-screen={screen}>
			{requestError !== undefined && <p role="alert">{requestError}</p>}
			<profileKit.Submit>Save profile</profileKit.Submit>
		</profileKit.AutoForm>
	)
}

"use client"
 
import type { FormSubmitDetails } from "form-please"
import {
	createLocalStorageAdapter,
	createPersistenceMiddleware,
	usePersistence,
} from "form-please/persistence"
import { nativeFormKit } from "form-please/preset-native"
import { useEffect, useState } from "react"
import { z } from "zod"
 
const releaseSchema = z.object({
	title: z.string().min(1, "Enter a title"),
	description: z.string().min(20, "Write at least 20 characters"),
})
const releaseDefinition = nativeFormKit.defineForm(releaseSchema, {
	ui: [
		{ kind: "field", path: "title", control: "text", label: "Title" },
		{
			kind: "field",
			path: "description",
			control: "textarea",
			label: "Description",
			props: { rows: 5 },
		},
	],
})
 
const releasePersistence = createPersistenceMiddleware({
	adapter: createLocalStorageAdapter(() => localStorage),
	key: "release-draft",
	version: 1,
})
 
type ValidatedIntent = "publish" | "save-and-close"
type ReleaseSubmitter = FormSubmitDetails<typeof releaseSchema>["submitter"]
 
function readValidatedIntent(submitter: ReleaseSubmitter): ValidatedIntent {
	if (submitter === null) return "publish"
	if (submitter.name !== "intent") {
		throw new TypeError(`Unknown submitter: ${submitter.name}`)
	}
	if (submitter.value === "publish" || submitter.value === "save-and-close") {
		return submitter.value
	}
	throw new TypeError(`Unknown submit intent: ${submitter.value}`)
}
 
function submitIntent(intent: ValidatedIntent) {
	return { name: "intent", value: intent } as const
}
 
async function sendRelease(
	value: z.output<typeof releaseSchema>,
	intent: ValidatedIntent,
): Promise<void> {
	const response = await fetch("/api/releases", {
		method: "POST",
		headers: { "content-type": "application/json" },
		body: JSON.stringify({ intent, release: value }),
	})
	if (!response.ok) throw new Error("The release could not be saved")
}
 
export function ReleaseActions({ onClose }: { readonly onClose: () => void }) {
	const [status, setStatus] = useState("Restoring the draft…")
	const form = nativeFormKit.useForm(releaseDefinition, {
		defaultValues: { title: "", description: "" },
		middleware: [releasePersistence],
		onSubmit: async ({ form, input, submitter, value }) => {
			const intent = readValidatedIntent(submitter)
			if (intent === "publish") setStatus("Publishing…")
			else setStatus("Saving…")
			await sendRelease(value, intent)
			await releasePersistence.handle(form).clear()
			form.api.reset(input)
			if (intent === "save-and-close") onClose()
			else setStatus("Published.")
		},
	})
	const persistence = usePersistence(form, releasePersistence)
	const persistenceState = persistence.snapshot
	const persistenceReady = persistenceState.phase === "active"
 
	useEffect(() => {
		if (persistenceState.phase === "active") setStatus("Draft ready.")
		else if (persistenceState.phase === "failed") {
			setStatus("The draft could not be restored.")
		} else if (persistenceState.phase === "conflict") {
			setStatus("The form changed before the draft could be restored.")
		}
	}, [persistenceState.phase])
 
	async function saveDraft() {
		setStatus("Saving draft…")
		try {
			await persistence.flush()
			setStatus("Draft saved.")
		} catch {
			setStatus("The draft could not be saved.")
		}
	}
 
	return (
		<nativeFormKit.AutoForm form={form}>
			<output aria-live="polite">{status}</output>
			<button
				disabled={!persistenceReady}
				type="button"
				onClick={() => void saveDraft()}
			>
				Save draft
			</button>
			<nativeFormKit.Submit
				{...submitIntent("publish")}
				disabled={!persistenceReady}
			>
				Publish
			</nativeFormKit.Submit>
			<nativeFormKit.Submit
				{...submitIntent("save-and-close")}
				disabled={!persistenceReady}
			>
				Save and close
			</nativeFormKit.Submit>
		</nativeFormKit.AutoForm>
	)
}

import type { FormSubmitDetails, StandardSchema } from "form-please"
 
type Input = { title: string }
declare const schema: StandardSchema<Input>
 
type Submitter
 = FormSubmitDetails<typeof schema>["submitter"]