Skip to content

Turned recipe projects into nestable folders. - #425

Closed
dfguerrerom wants to merge 52 commits into
masterfrom
feat/recipe-folders
Closed

dfguerrerom wants to merge 52 commits into
masterfrom
feat/recipe-folders

Conversation

@dfguerrerom

@dfguerrerom dfguerrerom commented Sep 15, 2026 •

Copy link
Copy Markdown
Contributor

This is a draft. Use it for discussion. Do not merge it.

This description is long. That is intentional. The notes below give the decisions and the problems that the code does not show. Read them before you change the behavior.

Projects are now folders. A folder can contain other folders. There is no limit to the depth. Recipes are the files in a folder. A click opens a folder, and the breadcrumb takes you back up. You can also drag a recipe or a folder onto a folder row, or onto a breadcrumb segment, to move it there. The projects menu is no longer there. That menu was a filter, not a container.

The change

The database. The migration 003.do.folders.sql makes a new table folder and copies each row of project into it. It adds the column recipe.folder_id and fills it from recipe.project_id, but only where that project exists and belongs to the same user. Every other value, the empty text included, stays NULL and shows at the root.

project and recipe.project_id stay in place. The legacy import reads project, and a statement that names a table which is not there fails whether or not its condition holds. A later migration drops both, after the imports in test and in production are complete. docs/database-migrations.md gives that step under "After the imports".

The server. The routes are POST /folder, POST /folder/:id and DELETE /folder/:id. A folder refuses a parent that makes a loop (FOLDER_CYCLE), and a parent that is not a folder of the same user (FOLDER_PARENT_NOT_FOUND). Removal refuses a folder that contains a folder or a recipe (FOLDER_NOT_EMPTY, with the counts). The move route uses the reserved id none for the root, and POST /folder refuses that id (FOLDER_ID_RESERVED). A recipe document no longer keeps projectId.

The interface. The module recipeTree.js does the calculations for the tree, and it has no interface code. The list is a folder navigator: a breadcrumb, folder rows with their counts, recipe rows, a folder picker for the destination of a move, and an undo for a move that was not intended. The picker has no breadcrumb, because the box is too narrow for a path: it names the folder you are in and gives a button back to the one above. Edit mode selects folders as well as recipes, and it ends when an action has used the selection. A folder name is limited to 50 characters, and a name too long for the space it is given is cut with an ellipsis, with the whole of it in a tooltip. Three components are gone: selectProject.jsx, projectsButton.jsx and projects.jsx. Redux no longer keeps process.filteredRecipes.

Notes for the next person

These are decisions. They are not accidents. Read them before you make a change.

The server does not remove the contents of a folder

Before this change, the server removed all the recipes in a project when it removed the project. That rule is not safe with folders, where one click can remove many levels of data. The server now refuses, with the HTTP status 409 and the counts. You must empty the folder first. Users will see this change. The list removes what it can and names what it left.

A value for "no folder" must be false

In JavaScript, a folder id that means "no folder" must be false. Three defects came from values that are true:

  • The empty text. The database keeps the id of a root recipe as '' as often as NULL. The operator ?? kept '' as '', and the root showed no recipes.
  • The text <no project>. The old menu gave that text as a destination, and the server wrote it into the column.
  • The value null in a URL path. The move put the destination in the path, and a root destination became the text "null".

A recipe with one of these values matches no folder, and it is not at the root either. The tree does not show it. Only a search finds it.

These are the guards: the function at() in recipeTree changes a false id to ROOT; the move route uses the reserved word none, which the server changes to SQL NULL; and POST /folder refuses that id, so no folder can hold it.

A fourth defect of this type is possible. If you change the code for a folder id, examine these four operations: a comparison, a URL that contains the id, a conversion to text, and a default value.

The server controls the rules of the tree

The folder picker does not offer a folder that is being moved, and it does not offer the folders below it. Drag and drop refuses the same moves. This prevents an incorrect parent in the interface, but it is only an aid. The repository makes the guarantee: it examines the parents inside the write transaction.

Two operations are not safe with more than one user

saveFolder and removeFolder read data, then they write data, in one transaction that does not lock the rows. There is no foreign key on recipe.folder_id, and none on folder.parent_id. A second user can make a recipe that has no folder. This change does not make the problem more frequent, but the result is worse than before: the list showed a recipe with an incorrect project id, and the tree does not show it. To correct this, use SELECT ... FOR UPDATE, or add foreign keys with ON DELETE RESTRICT. That is a decision about the database, and this branch does not make it.

A row changes only when its key changes

FastListItem is a PureComponent, and the list of items keeps the same identity when the selection changes. Thus itemKey must contain all the data that changes the row. The key did not contain the selection, and a defect was the result: the buttons changed, but the color of the row did not. When you add data to a row, add the same data to the key.

A drag is the exception. The row that is dragged must not change its key in the middle of the gesture, because a new row ends the drag. The valid drop target reaches the rows through a React context instead.

The words are different in the interface and in the new API

The interface and the new API both use the word folder. The word project remains in the old table, in the legacy import, and in the recipes that the import wrote. Both go together, with the migration named above.

Tests

recipeTree.js has no interface code, and the tests examine it directly: the loop-safe examination of the parents, the limits of the search, and the rules for a drop target. The tests of the components use createRoot and act, and they replace the widgets; widget/crudItem.test.jsx shows this method. recipeList.jsx now has tests, which it did not have before: the list, the selection, the removal that keeps a folder with contents, drag and drop, and the undo.

The repository, the routes and the migration have tests that use a MySQL database. These include: a parent value that goes to the database and comes back, the refusal of a loop, the refusal of an unknown parent, the protection of a folder of a different user, the refusal to remove a folder that has contents, the refusal of the reserved id, and the copy of the projects into folders.

Work that is not done

  • A record of the current folder after a page reload.
  • The full path of a folder in the Tasks page. That page shows the name of the folder only.
  • saveFolder and removeFolder do not lock the rows they read. The note above gives the two possible corrections.

Generated with the aid of claude-opus-5[1m], thinking level: maximum.

@dfguerrerom
dfguerrerom force-pushed the feat/recipe-folders branch 3 times, most recently from a954c79 to d747ef3 Compare October 23, 2026 08:42
@dfguerrerom
dfguerrerom added this pull request to stack #456 October 23, 2026 08:42
@dfguerrerom
dfguerrerom force-pushed the feat/recipe-folders branch 2 times, most recently from d68d40c to 8405ffd Compare October 26, 2026 09:53
@dfguerrerom
dfguerrerom removed this pull request from stack #456 October 30, 2026 08:17
@dfguerrerom
dfguerrerom changed the base branch from sepal-server to master October 30, 2026 08:18
@dfguerrerom

Copy link
Copy Markdown
Contributor Author

Replaced by #466, with the same code in four commits.

@lpaolini
lpaolini deleted the feat/recipe-folders branch November 18, 2026 15:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant