feat!: tag categories

README.md

@@ -71,12 +71,12 @@ Translation hosting generously provided by [Weblate](https://weblate.org/en/). C
 - Create libraries/vaults centered around a system directory. Libraries contain a series of entries: the representations of your files combined with metadata fields. Each entry represents a file in your library’s directory, and is linked to its location.
 - Address moved, deleted, or otherwise "unlinked" files by using the "Fix Unlinked Entries" option in the Tools menu.
 
-### Metadata + Tagging
+### Tagging + Custom Metadata
 
+- Add custom powerful tags to your library entries
 - Add metadata to your library entries, including:
   - Name, Author, Artist (Single-Line Text Fields)
   - Description, Notes (Multiline Text Fields)
-  - Tags, Meta Tags, Content Tags (Tag Boxes)
 - Create rich tags composed of a name, a list of aliases, and a list of “parent tags” - being tags in which these tags inherit values from.
 - Copy and paste tags and fields across file entries
 - Generate tags from your existing folder structure with the "Folders to Tags" macro (NOTE: these tags do NOT sync with folders after they are created)
@@ -136,20 +136,22 @@ 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
 
-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.
+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 here. 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 remove a tag from a file entry, hover over the tag in the preview panel and click on the "-" icon that appears.
+
+### Adding Metadata 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
 
 #### Text Line / Text Box
 
 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.
 

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,20 +11,21 @@ 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
 
 ### Text Line / Text Box
 
 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.

tagstudio/resources/translations/en.json

@@ -158,6 +158,8 @@
     "menu.file.close_library": "&Close Library",
     "menu.file.new_library": "New Library",
     "menu.file.open_create_library": "&Open/Create Library",
+    "menu.file.open_recent_library": "Open Recent",
+    "menu.file.clear_recent_libraries": "Clear Recent",
     "menu.file.open_library": "Open Library",
     "menu.file.refresh_directories": "&Refresh Directories",
     "menu.file.save_backup": "&Save Library Backup",

tagstudio/src/core/constants.py

@@ -1,3 +1,7 @@
+# Copyright (C) 2025
+# Licensed under the GPL-3.0 License.
+# Created for TagStudio: https://github.com/CyanVoxel/TagStudio
+
 VERSION: str = "9.5.0"  # Major.Minor.Patch
 VERSION_BRANCH: str = "EXPERIMENTAL"  # Usually "" or "Pre-Release"
 
@@ -11,7 +15,12 @@
 )
 FONT_SAMPLE_SIZES: list[int] = [10, 15, 20]
 
-TAG_FAVORITE = 1
+# NOTE: These were the field IDs used for the "Tags", "Content Tags", and "Meta Tags" fields inside
+# the legacy JSON database. These are used to help migrate libraries from JSON to SQLite.
+LEGACY_TAG_FIELD_IDS: set[int] = {6, 7, 8}
+
 TAG_ARCHIVED = 0
+TAG_FAVORITE = 1
+TAG_META = 2
 RESERVED_TAG_START = 0
 RESERVED_TAG_END = 999

tagstudio/src/core/enums.py

@@ -1,3 +1,7 @@
+# Copyright (C) 2025
+# Licensed under the GPL-3.0 License.
+# Created for TagStudio: https://github.com/CyanVoxel/TagStudio
+
 import enum
 from typing import Any
 from uuid import uuid4
@@ -20,10 +24,11 @@ class Theme(str, enum.Enum):
     COLOR_DARK_LABEL = "#DD000000"
     COLOR_BG = "#65000000"
 
-    COLOR_HOVER = "#65AAAAAA"
-    COLOR_PRESSED = "#65EEEEEE"
-    COLOR_DISABLED = "#65F39CAA"
-    COLOR_DISABLED_BG = "#65440D12"
+    COLOR_HOVER = "#65444444"
+    COLOR_PRESSED = "#65777777"
+    COLOR_DISABLED_BG = "#30000000"
+    COLOR_FORBIDDEN = "#65F39CAA"
+    COLOR_FORBIDDEN_BG = "#65440D12"
 
 
 class OpenStatus(enum.IntEnum):
@@ -65,4 +70,4 @@ class LibraryPrefs(DefaultEnum):
     IS_EXCLUDE_LIST = True
     EXTENSION_LIST: list[str] = [".json", ".xmp", ".aae"]
     PAGE_SIZE: int = 500
-    DB_VERSION: int = 2
+    DB_VERSION: int = 3

tagstudio/src/core/library/alchemy/db.py

@@ -1,3 +1,7 @@
+# Copyright (C) 2025
+# Licensed under the GPL-3.0 License.
+# Created for TagStudio: https://github.com/CyanVoxel/TagStudio
+
 from pathlib import Path
 
 import structlog
@@ -44,7 +48,10 @@ def make_tables(engine: Engine) -> None:
         autoincrement_val = result.scalar()
         if not autoincrement_val or autoincrement_val <= RESERVED_TAG_END:
             conn.execute(
-                text(f"INSERT INTO tags (id, name, color) VALUES ({RESERVED_TAG_END}, 'temp', 1)")
+                text(
+                    "INSERT INTO tags (id, name, color, is_category) VALUES "
+                    f"({RESERVED_TAG_END}, 'temp', 1, false)"
+                )
             )
             conn.execute(text(f"DELETE FROM tags WHERE id = {RESERVED_TAG_END}"))
             conn.commit()

tagstudio/src/core/library/alchemy/fields.py

@@ -1,3 +1,7 @@
+# Copyright (C) 2025
+# Licensed under the GPL-3.0 License.
+# Created for TagStudio: https://github.com/CyanVoxel/TagStudio
+
 from __future__ import annotations
 
 from dataclasses import dataclass, field
@@ -11,7 +15,7 @@
 from .enums import FieldTypeEnum
 
 if TYPE_CHECKING:
-    from .models import Entry, Tag, ValueType
+    from .models import Entry, ValueType
 
 
 class BaseField(Base):
@@ -75,33 +79,11 @@ def __key(self) -> tuple:
     def __eq__(self, value) -> bool:
         if isinstance(value, TextField):
             return self.__key() == value.__key()
-        elif isinstance(value, (TagBoxField, DatetimeField)):
+        elif isinstance(value, DatetimeField):
             return False
         raise NotImplementedError
 
 
-class TagBoxField(BaseField):
-    __tablename__ = "tag_box_fields"
-
-    tags: Mapped[set[Tag]] = relationship(secondary="tag_fields")
-
-    def __key(self):
-        return (
-            self.entry_id,
-            self.type_key,
-        )
-
-    @property
-    def value(self) -> None:
-        """For interface compatibility with other field types."""
-        return None
-
-    def __eq__(self, value) -> bool:
-        if isinstance(value, TagBoxField):
-            return self.__key() == value.__key()
-        raise NotImplementedError
-
-
 class DatetimeField(BaseField):
     __tablename__ = "datetime_fields"
 
@@ -133,9 +115,6 @@ class _FieldID(Enum):
     URL = DefaultField(id=3, name="URL", type=FieldTypeEnum.TEXT_LINE)
     DESCRIPTION = DefaultField(id=4, name="Description", type=FieldTypeEnum.TEXT_LINE)
     NOTES = DefaultField(id=5, name="Notes", type=FieldTypeEnum.TEXT_BOX)
-    TAGS = DefaultField(id=6, name="Tags", type=FieldTypeEnum.TAGS)
-    TAGS_CONTENT = DefaultField(id=7, name="Content Tags", type=FieldTypeEnum.TAGS, is_default=True)
-    TAGS_META = DefaultField(id=8, name="Meta Tags", type=FieldTypeEnum.TAGS, is_default=True)
     COLLATION = DefaultField(id=9, name="Collation", type=FieldTypeEnum.TEXT_LINE)
     DATE = DefaultField(id=10, name="Date", type=FieldTypeEnum.DATETIME)
     DATE_CREATED = DefaultField(id=11, name="Date Created", type=FieldTypeEnum.DATETIME)

tagstudio/src/core/library/alchemy/joins.py

@@ -1,18 +1,22 @@
+# Copyright (C) 2025
+# Licensed under the GPL-3.0 License.
+# Created for TagStudio: https://github.com/CyanVoxel/TagStudio
+
 from sqlalchemy import ForeignKey
 from sqlalchemy.orm import Mapped, mapped_column
 
 from .db import Base
 
 
-class TagSubtag(Base):
-    __tablename__ = "tag_subtags"
+class TagParent(Base):
+    __tablename__ = "tag_parents"
 
     parent_id: Mapped[int] = mapped_column(ForeignKey("tags.id"), primary_key=True)
     child_id: Mapped[int] = mapped_column(ForeignKey("tags.id"), primary_key=True)
 
 
-class TagField(Base):
-    __tablename__ = "tag_fields"
+class TagEntry(Base):
+    __tablename__ = "tag_entries"
 
-    field_id: Mapped[int] = mapped_column(ForeignKey("tag_box_fields.id"), primary_key=True)
     tag_id: Mapped[int] = mapped_column(ForeignKey("tags.id"), primary_key=True)
+    entry_id: Mapped[int] = mapped_column(ForeignKey("entries.id"), primary_key=True)