Document form state management #246

New issue

Open

opened 2025-11-10 21:03:15 +00:00 by jsheunis · 0 comments

jsheunis commented

2025-11-10 21:03:15 +00:00

(Migrated from github.com)

Recent experience with several issues:

has brought to light that the way in which shacl-vue manages form state, and related to that graph-vs-form-data state, is complex (likely much more than it needs to be) and largely undocumented.

In order to make future contributions/debugging easier, this whole design should be documented. Ideally this process will also lead to some code refactoring to yield less complexity.

Questions that need to be answered by the documentation (that I can think of at the moment):

what is the purpose of formData (from shacl-tulip's FormBase)?
when is formData used, and when is it unnecessary?
what does it mean if formData is saved to the graph store?
which components (can/should/might/do) have access to formData?
what is the purpose of:
- lastSavedNode
- openForms
- openForms[i].activatedInstancesSelectEditor
- savedNodes
- submittedNodes
- nodesToSubmit
...

IdeaS:

consider moving openForms and related functions (addForm, removeForm, formOpen, more?) to the useForm composable
move management of the "all fields" button state to openForms?
consider adding a general "activatedFrom" or something like that, to replace the more specific activatedInstancesSelectEditor, because a form could be opened from (also needs to be documented):
- ShaclVue main component, create new item
- InstancesSelectEditor "Add item"
- InstancesSelectEditor item edit button
- NodeShapeVieweredit button

Recent experience with several issues: - https://github.com/psychoinformatics-de/shacl-vue/issues/243 - https://github.com/psychoinformatics-de/shacl-vue/issues/244 - https://github.com/psychoinformatics-de/shacl-vue/issues/147 has brought to light that the way in which `shacl-vue` manages form state, and related to that graph-vs-form-data state, is complex (likely much more than it needs to be) and largely undocumented. In order to make future contributions/debugging easier, this whole design should be documented. Ideally this process will also lead to some code refactoring to yield less complexity. Questions that need to be answered by the documentation (that I can think of at the moment): - what is the purpose of `formData` (from `shacl-tulip`'s `FormBase`)? - when is `formData` used, and when is it unnecessary? - what does it mean if `formData` is saved to the graph store? - which components (can/should/might/do) have access to `formData`? - what is the purpose of: - `lastSavedNode` - `openForms` - `openForms[i].activatedInstancesSelectEditor` - `savedNodes` - `submittedNodes` - `nodesToSubmit` - ... IdeaS: - consider moving `openForms` and related functions (`addForm`, `removeForm`, `formOpen`, more?) to the `useForm` composable - move management of the "all fields" button state to `openForms`? - consider adding a general "activatedFrom" or something like that, to replace the more specific `activatedInstancesSelectEditor`, because a form could be opened from (also needs to be documented): - `ShaclVue` main component, create new item - `InstancesSelectEditor` "Add item" - `InstancesSelectEditor` item edit button - `NodeShapeViewer`edit button