Form State Management & Auto-Save

This document explains the high-level design of form states, auto-save policies, and navigation interception in the Desk UI.

1. Dirty State Detection

To prevent accidental data loss, the Desk monitors forms for changes:

Initial State: When a form loads, the initial state is stored.
Comparison: The form component continuously tracks field edits. If current values differ from the loaded state, the form is marked as dirty.
Visual Indicators: Save buttons are highlighted, and warning prompts are configured for exit handlers.

When a form is dirty, Framework M prevents accidental exits:

Routing Interception: Using the React Router v6.4+ Data Router, the application registers custom navigation blocking.
useBlocker Mechanism: When the route changes (e.g. sidebar navigation, backward history), the custom router interceptor blocks the route transition and displays a warning dialog.
Browser Exit Safeguards: A standard beforeunload event listener is attached to the browser window to intercept external page reloads or tab closures.

For DocTypes requiring high-density input or automated persistence:

Declaration: Enabled in Python metadata via auto_save = True inside the DocType Meta definition.
Debounced Triggers: The frontend debounces field input changes. After a brief period of inactivity (e.g., 1000ms), it automatically initiates a backend PUT or POST request to save the document.
Feedback: A saving spinner is displayed in the toolbar header, notifying the user when their progress is safely saved.

To support shareable links and consistent browser history:

Filter Synchronization: Filters, pagination, and sorting options in list, tree, Kanban, and Calendar views are driven entirely by the URL query parameters.
Refine.dev Hooks: The UI reads and writes query params dynamically. Reloading the page or copying the link preserves the active layout filters exactly.