feat!: tag categories (#655)

* refactor: remove TagBoxField and TagField (NOT WORKING)

* refactor: remove tag field types

* ci: fix mypy and ruff tests

* refactor: split up preview_panel

* fix: search now uses `TagEntry` (#656)

* fix: move theme check inside class

* refactor: reimplement file previews

* refactor: modularize `file_attributes.py`

* ui: show fields in preview panel

known issues:
- fields to not visually update after being edited until the entries are reloaded from the thumbnail grid (yes, the thumbnail grid)
- add field button currently non-functional
- surprise segfaults

* search: remove TagEntry join

* fix: remove extra `self.filter` assignment

* add success return flag to `add_tags_to_entry()`

* refactor: use entry IDs instead of objects and indices

- fixes preview panel not updating after entry edits
- fixes slow selection performance
- fixes double render call

* feat: add tag categories to preview panel

* ui: add "is category" checkbox in tag panel

* fix: tags can be compared for name sorting

* fix: don't add tags to previous selections

* fix: badges now properly update

* ui: hide sizeGrip

* ui: add blue ui color

* ui: display empty selection; better multi-selection

* cleanup comments; rename tsp to tag_search_panel

* fix(ui): properly unset container callbacks

* fix: optimize queries

* fix: catch int cast exception

* fix: remove unnecessary update calls

* fix: restore try/except block in preview_panel

* fix: correct type hints for get_tag_categories

* fix: tags no longer lazy load subtags and aliases

* fix: recursively include parent tag categories

* chore: update copyright info

* chore: remove unused code

* fix: load fields for selected entry

* refactor: remove `is_connected` from AddFieldModal

* fix: include category tags under their own categories

* fix: badges now update when last tag is removed

* fix: resolve differences with main

* fix: return empty set in place of `None`

* ui: add field highlighting, tweak theming

* refactor!: eradicate use of the term "subtag"

- Removes ambiguity between the use of the term "parent tag" and "subtag"
- Fixes inconstancies between the use of the term "subtag" to refer to either parent tags or child tags
- Fixes duplicate and ambiguous subtags mapped relationship for the Tag model
- Does NOT fix tests

* fix: catch and show library load errors

* tests: fix and/or remove tests

* suppress db preference warnings

* tests: add field container tests

* tests: add tag category tests

* refactor(ui): move recent libraries list to file menu

* docs: update roadmap and docs for tag categories

* fix: restore json migration functionality

* logs: remove/update debug logs

* chore: remove unused code

* tests: remove tests related to `TagBoxWidget`

* ui: optimize selection and badge updates

* docs: update usage

* fix: change typo of `tag.id` to `tag_id`

Co-authored-by: Jann Stute <46534683+Computerdores@users.noreply.github.com>

* fix: use term "child tags" instead of "subtags" in docstring

Co-authored-by: Jann Stute <46534683+Computerdores@users.noreply.github.com>

* fix: reference `child_id` instead of `parent_id` when deleting tags

Co-Authored-By: Jann Stute <46534683+Computerdores@users.noreply.github.com>

* add TODO comment for `update_thumbs()` optimization

* fix: combine and check (most) built-in tag data from JSON

Known issue: Tag colors from built-in JSON tags are not updated. This can be seen in the failing test.

* refactor: rename `select_item()` to `toggle_item_selection()`

* add TODO to optimize `add_tags_to_entry()`

* fix: remove unnecessary joins in search

* Revert "fix: remove unnecessary joins in search"

This reverts commit 4c019ca19c.

* fix: remove unnecessary joins in search

* reremove unused method `get_all_child_tag_ids()`

* fix: migrate user-edited tag colors for built-in tags

* style: update header for contributor-created files

* fix: use absolute path in "open file" context menu

* chore: change paramater type hint

---------

Co-authored-by: python357-1 <jb2101554@gmail.com>
Co-authored-by: Jann Stute <46534683+Computerdores@users.noreply.github.com>

docs/library/tag_categories.md

@@ -1,8 +1,15 @@
 ---
 tags:
-  - Upcoming Feature
 ---
 
-# Tag Categories
+# Tag Categories (v9.5)
 
-Replaces [Tag Fields](field.md#tag_box). Tags are able to be marked as a “category” which then displays as tag fields currently do, with any tags inheriting from that category being displayed underneath.
+The "Is Category" property of tags determines if a tag should be treated as a category itself when being organized inside the preview panel. Tags marked as categories will show themselves and all tags inheriting from it (including recursively) underneath a field-like section with the tag's name. This means that duplicates of tags can appear on entries if the tag inherits from multiple parent categories, however this is by design and reflects the nature multiple inheritance. Any tags not inheriting from a category tag will simply show under a default "Tag" section.
+
+### Built-In Tags and Categories
+
+The built-in tags "Favorite" and "Archived" inherit from the built-in "Meta Tags" category which is marked as a category by default. This behavior of default tags can be fully customized by disabling the category option and/or by adding/removing the tags' Parent Tags.
+
+### Migrating from v9.4 Libraries
+
+Due to the nature of how tags and Tag Felids operated prior to v9.5, the organization style of Tag Categories vs Tag Fields is not 1:1. Instead of tags being organized into fields on a per-entry basis, tags themselves determine their organizational layout via the "Is Property" flag. Any tags _(not currently inheriting from either the "Favorite" or "Archived" tags)_ will be shown under the default "Tags" header upon migrating to the v9.5+ library format. Similar organization to Tag Fields can be achieved by using the built-in "Meta Tags" tag or any other marked with "Is Category" and then setting those tags as parents for other tags to inherit from.

docs/updates/roadmap.md

@@ -34,8 +34,8 @@ Features are broken up into the following priority levels, with nested prioritie
         -   [ ] Existing colors are now a set of base colors [HIGH]
             -   [ ] Editable [MEDIUM]
             -   [ ] Non-removable [HIGH]
-    -   [ ] [Tag Categories](../library/tag_categories.md) [HIGH]
-        -   [ ] Property available for tags that allow the tag and any inheriting from it to be displayed separately in the preview panel under a title [HIGH]
+    -   [x] [Tag Categories](../library/tag_categories.md) [HIGH]
+        -   [x] Property available for tags that allow the tag and any inheriting from it to be displayed separately in the preview panel under a title [HIGH]
         -   [ ] Title is tag name [HIGH]
         -   [ ] Title has tag color [MEDIUM]
         -   [ ] Tag marked as category does not display as a tag itself [HIGH]
@@ -170,8 +170,8 @@ These version milestones are rough estimations for when the previous core featur
         -   [ ] Existing colors are now a set of base colors [HIGH]
             -   [ ] Editable [MEDIUM]
             -   [ ] Non-removable [HIGH]
-    -   [ ] [Tag Categories](../library/tag_categories.md) [HIGH]
-        -   [ ] Property available for tags that allow the tag and any inheriting from it to be displayed separately in the preview panel under a title [HIGH]
+    -   [x] [Tag Categories](../library/tag_categories.md) [HIGH]
+        -   [x] Property available for tags that allow the tag and any inheriting from it to be displayed separately in the preview panel under a title [HIGH]
 -   [ ] Search engine [HIGH]
     -   [x] Boolean operators [HIGH]
     -   [ ] Tag objects + autocomplete [HIGH]

docs/usage.md

@@ -11,9 +11,14 @@ In order to scan for new files or file changes, you’ll need to manually go to
 !!! note
     In the future, library refreshing will also be automatically done in the background, or additionally on app startup.
 
-## Adding Metadata to Entries
+## Adding Tags to File Entries
+Click the "Add Tag" button at the bottom of the preview panel with one or more tags selected. Search for existing inside the new dialog popup or create a new one from. Click the “+” button next to whichever tags you want to add. Alternatively, after you search for a tag, press the Enter/Return key to add the first item in the list. Press Enter/Return once more to close the dialog box.
 
-To add a metadata field to a file entry, start by clicking the “Add Field” button under the file preview in the right-hand preview panel. From the dropdown menu, select the type of metadata field you’d like to add to the entry.
+To remove a tag from a file entry, hover over the tag in the preview panel and click on the "-" icon that appears.
+
+## Adding Metadata Fields to File Entries
+
+To add a metadata field to a file entry, start by clicking the “Add Field” button at the bottom of the preview panel. From the dropdown menu, select the type of metadata field you’d like to add to the entry.
 
 ## Editing Metadata Fields
 
@@ -21,10 +26,6 @@ To add a metadata field to a file entry, start by clicking the “Add Field” b
 
 Hover over the field and click the pencil icon. From there, add or edit text in the dialog box popup.
 
-### Tag Box
-
-Click the “+” button at the end of the Tags list, and search for tags to add inside the new dialog popup. Click the “+” button next to whichever tags you want to add. Alternatively, after you search for a tag, press the Enter/Return key to add the add the first item in the list. Press Enter/Return once more to close the dialog box
-
 !!! warning
     Keyboard control and navigation is currently _very_ buggy, but will be improved in future versions.
 
@@ -51,6 +52,10 @@ Inevitably, some of the files inside your library will be renamed, moved, or del
 !!! warning
     If multiple matches for a moved file are found (matches are currently defined as files with a matching filename as the original), TagStudio will currently ignore the match groups. Adding a GUI for manual selection, as well as smarter automated relinking, are top priorities for future versions.
 
+## Deleting Tags
+
+To delete a tag from your library, go to File -> Tag Manager, hover over the tag you wish to delete, and click the "-" icon that appears. You will be prompted to make sure you wish to delete this tag from your library and across all file entries.
+
 ## Saving the Library
 
 Libraries are saved upon exiting the program. To manually save, select File -> Save Library from the menu bar. To save a backup of your library, select File -> Save Library Backup from the menu bar.