Skip to content

ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.

refactor(frontend): standardize form lifecycle

Juan Denisd0f4fa03e53e
diff --git a/frontend/src/components/settings/UserModal.jsx b/frontend/src/components/settings/UserModal.jsx
index a48622b3..d16c1fe4 100644
--- a/frontend/src/components/settings/UserModal.jsx
+++ b/frontend/src/components/settings/UserModal.jsx
@@ -8,44 +8,37 @@ import { Input } from '@/components/ui/input';
import { Label } from '@/components/ui/label';
import { Checkbox } from '@/components/ui/checkbox';
import { Select, SelectTrigger, SelectContent, SelectItem, SelectValue } from '@/components/ui/select';
+import FormField, { FormRow } from '../FormField';
+import useForm from '../../hooks/useForm';
+import { userPayload, validateUser, valuesForUser } from './userForm';
const UserModal = ({ user, onSave, onClose }) => {
- const [formData, setFormData] = useState({
- email: '',
- username: '',
- password: '',
- confirmPassword: '',
- role: 'developer',
- is_active: true
- });
const [permissions, setPermissions] = useState({});
const [showPermissions, setShowPermissions] = useState(false);
const [templates, setTemplates] = useState({});
- const [error, setError] = useState('');
- const [loading, setLoading] = useState(false);
const { user: currentUser } = useAuth();
const isEditing = !!user;
const isSelf = user?.id === currentUser?.id;
+ const form = useForm({
+ initialValues: valuesForUser(user),
+ validate: (values) => validateUser(values, { isEditing }),
+ onSubmit: async (values) => {
+ await onSave(userPayload(values, {
+ permissions,
+ includePermissions: showPermissions,
+ }));
+ },
+ });
+ const resetForm = form.reset;
useEffect(() => {
- if (user) {
- setFormData({
- email: user.email || '',
- username: user.username || '',
- password: '',
- confirmPassword: '',
- role: user.role || 'developer',
- is_active: user.is_active !== false
- });
- if (user.permissions) {
- setPermissions(user.permissions);
- // Show permissions section if user has custom permissions set
- const hasCustom = user.permissions && Object.keys(user.permissions).length > 0;
- setShowPermissions(hasCustom);
- }
- }
- }, [user]);
+ resetForm(valuesForUser(user));
+ const nextPermissions = user?.permissions || {};
+ setPermissions(nextPermissions);
+ // Show permissions section if user has custom permissions set
+ setShowPermissions(Object.keys(nextPermissions).length > 0);
+ }, [user, resetForm]);
useEffect(() => {
api.getPermissionTemplates().then(data => {
@@ -53,144 +46,75 @@ const UserModal = ({ user, onSave, onClose }) => {
}).catch(() => {});
}, []);
- function handleChange(e) {
- const { name, value, type, checked } = e.target;
- setFormData(prev => ({
- ...prev,
- [name]: type === 'checkbox' ? checked : value
- }));
- // When role changes, load template defaults for the permissions editor
- if (name === 'role' && templates[value]) {
- setPermissions(templates[value]);
- }
- }
-
function handleRoleChange(newRole) {
- setFormData(prev => ({ ...prev, role: newRole }));
+ form.setValue('role', newRole);
if (templates[newRole]) {
setPermissions(templates[newRole]);
}
}
- async function handleSubmit(e) {
- e.preventDefault();
- setError('');
-
- // Validation
- if (!formData.email || !formData.username) {
- setError('Email and username are required');
- return;
- }
-
- if (!isEditing && !formData.password) {
- setError('Password is required for new users');
- return;
- }
-
- if (formData.password && formData.password.length < 8) {
- setError('Password must be at least 8 characters');
- return;
- }
-
- if (formData.password && formData.password !== formData.confirmPassword) {
- setError('Passwords do not match');
- return;
- }
-
- setLoading(true);
-
- try {
- const userData = {
- email: formData.email,
- username: formData.username,
- role: formData.role,
- is_active: formData.is_active
- };
-
- // Only include password if it's been set
- if (formData.password) {
- userData.password = formData.password;
- }
-
- // Include custom permissions if editor is open and role isn't admin
- if (showPermissions && formData.role !== 'admin') {
- userData.permissions = permissions;
- }
-
- await onSave(userData);
- } catch (err) {
- setError(err.message || 'Failed to save user');
- } finally {
- setLoading(false);
- }
- }
-
return (
<Modal open={true} onClose={onClose} title={isEditing ? 'Edit User' : 'Add New User'} size="md">
- <form onSubmit={handleSubmit}>
+ <form onSubmit={form.handleSubmit}>
<div className="modal-body">
- {error && <div className="error-message">{error}</div>}
+ {form.submitError && <div className="error-message" role="alert">{form.submitError}</div>}
- <div className="form-group">
- <Label htmlFor="email">Email</Label>
+ <FormField label="Email" htmlFor="email" required error={form.getFieldError('email')}>
<Input
+ {...form.getFieldProps('email')}
type="email"
id="email"
- name="email"
- value={formData.email}
- onChange={handleChange}
placeholder="[email protected]"
required
/>
- </div>
+ </FormField>
- <div className="form-group">
- <Label htmlFor="username">Username</Label>
+ <FormField label="Username" htmlFor="username" required error={form.getFieldError('username')}>
<Input
+ {...form.getFieldProps('username')}
type="text"
id="username"
- name="username"
- value={formData.username}
- onChange={handleChange}
placeholder="Enter username"
required
/>
- </div>
-
- <div className="form-row">
- <div className="form-group">
- <Label htmlFor="password">
- {isEditing ? 'New Password (leave blank to keep current)' : 'Password'}
- </Label>
+ </FormField>
+
+ <FormRow>
+ <FormField
+ label={isEditing ? 'New Password (leave blank to keep current)' : 'Password'}
+ htmlFor="password"
+ required={!isEditing}
+ error={form.getFieldError('password')}
+ >
<Input
+ {...form.getFieldProps('password')}
type="password"
id="password"
- name="password"
- value={formData.password}
- onChange={handleChange}
placeholder={isEditing ? 'Leave blank to keep current' : 'At least 8 characters'}
required={!isEditing}
/>
- </div>
+ </FormField>
- <div className="form-group">
- <Label htmlFor="confirmPassword">Confirm Password</Label>
+ <FormField
+ label="Confirm Password"
+ htmlFor="confirmPassword"
+ required={Boolean(form.values.password)}
+ error={form.getFieldError('confirmPassword')}
+ >
<Input
+ {...form.getFieldProps('confirmPassword')}
type="password"
id="confirmPassword"
- name="confirmPassword"
- value={formData.confirmPassword}
- onChange={handleChange}
placeholder="Confirm password"
- required={!!formData.password}
+ required={Boolean(form.values.password)}
/>
- </div>
- </div>
+ </FormField>
+ </FormRow>
<div className="form-group">
<Label htmlFor="role">Role</Label>
<Select
- value={formData.role}
+ value={form.values.role}
onValueChange={handleRoleChange}
disabled={isSelf}
>
@@ -212,8 +136,8 @@ const UserModal = ({ user, onSave, onClose }) => {
<label className="checkbox-label">
<Checkbox
name="is_active"
- checked={formData.is_active}
- onCheckedChange={(checked) => setFormData(prev => ({ ...prev, is_active: checked }))}
+ checked={form.values.is_active}
+ onCheckedChange={(checked) => form.setValue('is_active', Boolean(checked))}
disabled={isSelf}
/>
<span className="checkbox-text">Account is active</span>
@@ -239,21 +163,21 @@ const UserModal = ({ user, onSave, onClose }) => {
</div>
</div>
- {formData.role !== 'admin' && (
+ {form.values.role !== 'admin' && (
<div className="customize-permissions-section">
<Button
type="button"
variant="ghost"
size="sm"
onClick={() => {
- if (!showPermissions && templates[formData.role]) {
- setPermissions(templates[formData.role]);
+ if (!showPermissions && templates[form.values.role]) {
+ setPermissions(templates[form.values.role]);
}
setShowPermissions(!showPermissions);
}}
>
{showPermissions ? 'Hide' : 'Customize'} Permissions
- <svg viewBox="0 0 24 24" width="14" height="14" stroke="currentColor" fill="none" strokeWidth="2" style={{ marginLeft: 4 }}>
+ <svg viewBox="0 0 24 24" width="14" height="14" stroke="currentColor" fill="none" strokeWidth="2">
{showPermissions
? <polyline points="18 15 12 9 6 15"/>
: <polyline points="6 9 12 15 18 9"/>
@@ -274,8 +198,8 @@ const UserModal = ({ user, onSave, onClose }) => {
<Button type="button" variant="ghost" onClick={onClose}>
Cancel
</Button>
- <Button type="submit" variant="default" disabled={loading}>
- {loading ? 'Saving...' : (isEditing ? 'Save Changes' : 'Create User')}
+ <Button type="submit" variant="default" disabled={form.isSubmitting}>
+ {form.isSubmitting ? 'Saving...' : (isEditing ? 'Save Changes' : 'Create User')}
</Button>
</div>
</form>
diff --git a/frontend/src/components/settings/__tests__/userForm.test.mjs b/frontend/src/components/settings/__tests__/userForm.test.mjs
new file mode 100644
index 00000000..6f138565
--- /dev/null
+++ b/frontend/src/components/settings/__tests__/userForm.test.mjs
@@ -0,0 +1,84 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import {
+ EMPTY_USER_FORM,
+ userPayload,
+ validateUser,
+ valuesForUser,
+} from '../userForm.js';
+
+test('user form derives safe create and edit values', () => {
+ assert.deepEqual(valuesForUser(null), { ...EMPTY_USER_FORM });
+ assert.deepEqual(valuesForUser({
+ email: '[email protected]',
+ username: 'ada',
+ role: 'admin',
+ is_active: false,
+ password: 'must-not-be-copied',
+ }), {
+ ...EMPTY_USER_FORM,
+ email: '[email protected]',
+ username: 'ada',
+ role: 'admin',
+ is_active: false,
+ });
+});
+
+test('new users require a valid matching password', () => {
+ const values = {
+ ...EMPTY_USER_FORM,
+ email: '[email protected]',
+ username: 'user',
+ password: 'short',
+ confirmPassword: 'different',
+ };
+
+ assert.deepEqual(validateUser(values), {
+ password: 'Password must be at least 8 characters',
+ confirmPassword: 'Passwords do not match',
+ });
+ assert.deepEqual(validateUser({ ...values, password: '', confirmPassword: '' }), {
+ password: 'Password is required for new users',
+ });
+});
+
+test('edits permit a blank password and payloads omit confirmation state', () => {
+ const values = {
+ ...EMPTY_USER_FORM,
+ email: ' [email protected] ',
+ username: ' user ',
+ };
+
+ assert.deepEqual(validateUser(values, { isEditing: true }), {});
+ assert.deepEqual(userPayload(values, {
+ permissions: { applications: ['read'] },
+ includePermissions: true,
+ }), {
+ email: '[email protected]',
+ username: 'user',
+ role: 'developer',
+ is_active: true,
+ permissions: { applications: ['read'] },
+ });
+});
+
+test('admin payloads never include custom permissions', () => {
+ assert.deepEqual(userPayload({
+ ...EMPTY_USER_FORM,
+ email: '[email protected]',
+ username: 'admin',
+ role: 'admin',
+ password: 'long-enough',
+ confirmPassword: 'long-enough',
+ }, {
+ permissions: { applications: [] },
+ includePermissions: true,
+ }), {
+ email: '[email protected]',
+ username: 'admin',
+ role: 'admin',
+ is_active: true,
+ password: 'long-enough',
+ });
+});
diff --git a/frontend/src/components/settings/userForm.js b/frontend/src/components/settings/userForm.js
new file mode 100644
index 00000000..c319dc06
--- /dev/null
+++ b/frontend/src/components/settings/userForm.js
@@ -0,0 +1,46 @@
+export const EMPTY_USER_FORM = Object.freeze({
+ email: '',
+ username: '',
+ password: '',
+ confirmPassword: '',
+ role: 'developer',
+ is_active: true,
+});
+
+export function valuesForUser(user) {
+ if (!user) return { ...EMPTY_USER_FORM };
+
+ return {
+ ...EMPTY_USER_FORM,
+ email: user.email || '',
+ username: user.username || '',
+ role: user.role || 'developer',
+ is_active: user.is_active !== false,
+ };
+}
+
+export function validateUser(values, { isEditing = false } = {}) {
+ const errors = {};
+ if (!values.email?.trim()) errors.email = 'Email is required';
+ if (!values.username?.trim()) errors.username = 'Username is required';
+ if (!isEditing && !values.password) errors.password = 'Password is required for new users';
+ if (values.password && values.password.length < 8) {
+ errors.password = 'Password must be at least 8 characters';
+ }
+ if (values.password && values.password !== values.confirmPassword) {
+ errors.confirmPassword = 'Passwords do not match';
+ }
+ return errors;
+}
+
+export function userPayload(values, { permissions, includePermissions = false } = {}) {
+ const payload = {
+ email: values.email.trim(),
+ username: values.username.trim(),
+ role: values.role,
+ is_active: values.is_active,
+ };
+ if (values.password) payload.password = values.password;
+ if (includePermissions && values.role !== 'admin') payload.permissions = permissions;
+ return payload;
+}
diff --git a/frontend/src/hooks/__tests__/formState.test.mjs b/frontend/src/hooks/__tests__/formState.test.mjs
new file mode 100644
index 00000000..6553e06d
--- /dev/null
+++ b/frontend/src/hooks/__tests__/formState.test.mjs
@@ -0,0 +1,77 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import {
+ createFormState,
+ dirtyFieldsFor,
+ formReducer,
+ mapServerFormError,
+ normalizeFieldErrors,
+ touchedFieldsFor,
+} from '../formState.js';
+
+test('form state tracks changed fields and resets to a new record', () => {
+ const initial = createFormState({ name: 'Ada', active: true });
+ const changed = formReducer(initial, {
+ type: 'setValue',
+ name: 'name',
+ value: 'Grace',
+ clearError: true,
+ });
+
+ assert.deepEqual(changed.values, { name: 'Grace', active: true });
+ assert.deepEqual(dirtyFieldsFor(changed), { name: true });
+
+ const reset = formReducer(changed, {
+ type: 'reset',
+ values: { name: 'Linus', active: false },
+ });
+ assert.deepEqual(reset.values, { name: 'Linus', active: false });
+ assert.deepEqual(reset.touched, {});
+ assert.deepEqual(dirtyFieldsFor(reset), {});
+});
+
+test('validation failures reveal every field and preserve field messages', () => {
+ const initial = createFormState({ email: '', role: 'developer' });
+ const errors = normalizeFieldErrors({ email: ['Missing data.'] });
+ const invalid = formReducer(initial, {
+ type: 'validationFailed',
+ errors,
+ touched: touchedFieldsFor(initial.values),
+ });
+
+ assert.deepEqual(invalid.errors, { email: 'Missing data.' });
+ assert.deepEqual(invalid.touched, { email: true, role: true });
+ assert.equal(invalid.submitCount, 1);
+});
+
+test('server validation details map to fields without losing the request message', () => {
+ const error = new Error('Invalid request');
+ error.data = {
+ code: 'validation_error',
+ details: {
+ fields: {
+ email: ['Not a valid email address.'],
+ profile: { name: ['Required.'] },
+ },
+ },
+ };
+
+ assert.deepEqual(mapServerFormError(error), {
+ fieldErrors: {
+ email: 'Not a valid email address.',
+ profile: 'Required.',
+ },
+ formError: 'Invalid request',
+ });
+});
+
+test('legacy field error shapes remain consumable during API convergence', () => {
+ assert.deepEqual(mapServerFormError({
+ message: 'Could not save',
+ fieldErrors: { username: 'Already exists' },
+ }), {
+ fieldErrors: { username: 'Already exists' },
+ formError: 'Could not save',
+ });
+});
diff --git a/frontend/src/hooks/formState.js b/frontend/src/hooks/formState.js
new file mode 100644
index 00000000..4a4dacb9
--- /dev/null
+++ b/frontend/src/hooks/formState.js
@@ -0,0 +1,121 @@
+export const FORM_ERROR = '_form';
+
+const cloneValues = (values) => ({ ...(values || {}) });
+
+const errorText = (value) => {
+ if (Array.isArray(value)) {
+ return value.map(errorText).filter(Boolean).join(' ');
+ }
+ if (value && typeof value === 'object') {
+ return Object.values(value).map(errorText).filter(Boolean).join(' ');
+ }
+ return value == null ? '' : String(value);
+};
+
+export function normalizeFieldErrors(errors) {
+ if (!errors || typeof errors !== 'object' || Array.isArray(errors)) return {};
+
+ return Object.fromEntries(
+ Object.entries(errors)
+ .map(([field, value]) => [field, errorText(value)])
+ .filter(([, message]) => Boolean(message)),
+ );
+}
+
+export function mapServerFormError(error) {
+ const data = error?.data || error?.response?.data || {};
+ const candidates = [
+ error?.fieldErrors,
+ error?.errors,
+ data.field_errors,
+ data.errors,
+ data.details?.fields,
+ ];
+ const fieldErrors = candidates.reduce((result, candidate) => (
+ Object.keys(result).length > 0 ? result : normalizeFieldErrors(candidate)
+ ), {});
+
+ return {
+ fieldErrors,
+ formError: error?.message || data.error || data.message || 'Unable to save changes',
+ };
+}
+
+export function createFormState(initialValues = {}) {
+ const values = cloneValues(initialValues);
+ return {
+ initialValues: values,
+ values,
+ touched: {},
+ errors: {},
+ submitError: '',
+ submitCount: 0,
+ isSubmitting: false,
+ };
+}
+
+export function formReducer(state, action) {
+ switch (action.type) {
+ case 'setValue':
+ return {
+ ...state,
+ values: { ...state.values, [action.name]: action.value },
+ errors: action.clearError
+ ? { ...state.errors, [action.name]: undefined }
+ : state.errors,
+ submitError: action.clearError ? '' : state.submitError,
+ };
+ case 'setValues':
+ return {
+ ...state,
+ values: { ...state.values, ...action.values },
+ };
+ case 'touch':
+ return {
+ ...state,
+ touched: { ...state.touched, [action.name]: true },
+ };
+ case 'validationFailed':
+ return {
+ ...state,
+ errors: action.errors,
+ touched: action.touched,
+ submitError: action.errors[FORM_ERROR] || '',
+ submitCount: state.submitCount + 1,
+ };
+ case 'submitStarted':
+ return {
+ ...state,
+ errors: {},
+ submitError: '',
+ isSubmitting: true,
+ submitCount: state.submitCount + 1,
+ };
+ case 'submitFailed':
+ return {
+ ...state,
+ errors: action.errors,
+ touched: { ...state.touched, ...action.touched },
+ submitError: action.submitError,
+ isSubmitting: false,
+ };
+ case 'submitFinished':
+ return { ...state, isSubmitting: false };
+ case 'reset':
+ return createFormState(action.values);
+ default:
+ return state;
+ }
+}
+
+export function dirtyFieldsFor(state) {
+ return Object.fromEntries(
+ Object.keys(state.values)
+ .filter((name) => !Object.is(state.values[name], state.initialValues[name]))
+ .map((name) => [name, true]),
+ );
+}
+
+export function touchedFieldsFor(values) {
+ return Object.fromEntries(Object.keys(values).map((name) => [name, true]));
+}
diff --git a/frontend/src/hooks/useForm.js b/frontend/src/hooks/useForm.js
new file mode 100644
index 00000000..66cf1fbd
--- /dev/null
+++ b/frontend/src/hooks/useForm.js
@@ -0,0 +1,113 @@
+import { useCallback, useMemo, useReducer, useRef } from 'react';
+import {
+ createFormState,
+ dirtyFieldsFor,
+ formReducer,
+ mapServerFormError,
+ normalizeFieldErrors,
+ touchedFieldsFor,
+} from './formState';
+
+/**
+ * Owns form lifecycle state while leaving field rendering and domain payloads
+ * to the caller. `initialValues` are read on mount; call `reset(nextValues)`
+ * when an asynchronously loaded record changes.
+ */
+export default function useForm({ initialValues = {}, validate, onSubmit }) {
+ const [state, dispatch] = useReducer(formReducer, initialValues, createFormState);
+ const initialValuesRef = useRef(initialValues);
+ const validateRef = useRef(validate);
+ const onSubmitRef = useRef(onSubmit);
+ validateRef.current = validate;
+ onSubmitRef.current = onSubmit;
+
+ const dirtyFields = useMemo(() => dirtyFieldsFor(state), [state]);
+
+ const setValue = useCallback((name, value, { touch = false } = {}) => {
+ dispatch({ type: 'setValue', name, value, clearError: true });
+ if (touch) dispatch({ type: 'touch', name });
+ }, []);
+
+ const setValues = useCallback((values) => {
+ dispatch({ type: 'setValues', values });
+ }, []);
+
+ const setFieldTouched = useCallback((name) => {
+ dispatch({ type: 'touch', name });
+ }, []);
+
+ const handleChange = useCallback((event) => {
+ const { name, type, checked, value } = event.target;
+ setValue(name, type === 'checkbox' ? checked : value);
+ }, [setValue]);
+
+ const reset = useCallback((values) => {
+ const nextValues = values || initialValuesRef.current;
+ initialValuesRef.current = nextValues;
+ dispatch({ type: 'reset', values: nextValues });
+ }, []);
+
+ const handleSubmit = useCallback(async (event) => {
+ event?.preventDefault?.();
+ const values = state.values;
+ const errors = normalizeFieldErrors(
+ validateRef.current ? await validateRef.current(values) : {},
+ );
+ const touched = touchedFieldsFor(values);
+
+ if (Object.keys(errors).length > 0) {
+ dispatch({ type: 'validationFailed', errors, touched });
+ return { ok: false, errors };
+ }
+
+ dispatch({ type: 'submitStarted' });
+ try {
+ const result = await onSubmitRef.current?.(values);
+ dispatch({ type: 'submitFinished' });
+ return { ok: true, value: result };
+ } catch (error) {
+ const mapped = mapServerFormError(error);
+ const failedTouched = Object.fromEntries(
+ Object.keys(mapped.fieldErrors).map((name) => [name, true]),
+ );
+ dispatch({
+ type: 'submitFailed',
+ errors: mapped.fieldErrors,
+ touched: failedTouched,
+ submitError: mapped.formError,
+ });
+ return { ok: false, error, errors: mapped.fieldErrors };
+ }
+ }, [state.values]);
+
+ const getFieldError = useCallback((name) => (
+ state.touched[name] ? state.errors[name] : undefined
+ ), [state.errors, state.touched]);
+
+ const getFieldProps = useCallback((name) => ({
+ name,
+ value: state.values[name] ?? '',
+ onChange: handleChange,
+ onBlur: () => setFieldTouched(name),
+ 'aria-invalid': Boolean(getFieldError(name)),
+ }), [getFieldError, handleChange, setFieldTouched, state.values]);
+
+ return {
+ values: state.values,
+ errors: state.errors,
+ touched: state.touched,
+ dirtyFields,
+ isDirty: Object.keys(dirtyFields).length > 0,
+ isSubmitting: state.isSubmitting,
+ submitCount: state.submitCount,
+ submitError: state.submitError,
+ setValue,
+ setValues,
+ setFieldTouched,
+ getFieldError,
+ getFieldProps,
+ handleChange,
+ handleSubmit,
+ reset,
+ };
+}
diff --git a/frontend/src/styles/components/_users.scss b/frontend/src/styles/components/_users.scss
index 8c518f84..bd846515 100644
--- a/frontend/src/styles/components/_users.scss
+++ b/frontend/src/styles/components/_users.scss
@@ -443,6 +443,10 @@
> .btn {
margin-bottom: $space-2;
+
+ svg {
+ margin-left: $space-1;
+ }
}
}