✨(backend) allow masking documents from the list view

Once users have visited a document to which they have access,
they can't remove it from their list view anymore. Several
users reported that this is annoying because a document that
gets a lot of updates keeps popping up at the top of their list
view.

They want to be able to mask the document in a click. We propose
to add a "masked documents" section in the left side bar where the
masked documents can still be found.

Author: sampaccoud

CHANGELOG.md

@@ -10,6 +10,7 @@ and this project adheres to
 
 ### Added
 
+- ✨(backend) allow masking documents from the list view #1171
 - ✨(frontend) add duplicate action to doc tree #1175
 
 ### Changed
@@ -33,7 +34,6 @@ and this project adheres to
 
 - 🐛(backend) improve prompt to not use code blocks delimiter #1188
 
-
 ## [3.4.1] - 2025-07-15
 
 ### Fixed
@@ -58,7 +58,7 @@ and this project adheres to
 - ✨(backend) add ancestors links reach and role to document API #846
 - 📝(project) add troubleshoot doc #1066
 - 📝(project) add system-requirement doc #1066
-- 🔧(front) configure x-frame-options to DENY in nginx conf #1084
+- 🔧(frontend) configure x-frame-options to DENY in nginx conf #1084
 - ✨(backend) allow to disable checking unsafe mimetype on 
   attachment upload #1099
 - ✨(doc) add documentation to install with compose #855

src/backend/core/api/filters.py

@@ -60,6 +60,9 @@ class ListDocumentFilter(DocumentFilter):
     is_creator_me = django_filters.BooleanFilter(
         method="filter_is_creator_me", label=_("Creator is me")
     )
+    is_masked = django_filters.BooleanFilter(
+        method="filter_is_masked", label=_("Masked")
+    )
     is_favorite = django_filters.BooleanFilter(
         method="filter_is_favorite", label=_("Favorite")
     )
@@ -106,3 +109,22 @@ def filter_is_favorite(self, queryset, name, value):
             return queryset
 
         return queryset.filter(is_favorite=bool(value))
+
+    # pylint: disable=unused-argument
+    def filter_is_masked(self, queryset, name, value):
+        """
+        Filter documents based on whether they are masked by the current user.
+
+        Example:
+            - /api/v1.0/documents/?is_masked=true
+                → Filters documents marked as masked by the logged-in user
+            - /api/v1.0/documents/?is_masked=false
+                → Filters documents not marked as masked by the logged-in user
+        """
+        user = self.request.user
+
+        if not user.is_authenticated:
+            return queryset
+
+        queryset_method = queryset.filter if bool(value) else queryset.exclude
+        return queryset_method(link_traces__user=user, link_traces__is_masked=True)

src/backend/core/api/viewsets.py

@@ -455,9 +455,8 @@ def list(self, request, *args, **kwargs):
 
         # Annotate favorite status and filter if applicable as late as possible
         queryset = queryset.annotate_is_favorite(user)
-        queryset = filterset.filters["is_favorite"].filter(
-            queryset, filter_data["is_favorite"]
-        )
+        for field in ["is_favorite", "is_masked"]:
+            queryset = filterset.filters[field].filter(queryset, filter_data[field])
 
         # Apply ordering only now that everything is filtered and annotated
         queryset = filters.OrderingFilter().filter_queryset(
@@ -1109,15 +1108,50 @@ def favorite(self, request, *args, **kwargs):
             document=document, user=user
         ).delete()
         if deleted:
-            return drf.response.Response(
-                {"detail": "Document unmarked as favorite"},
-                status=drf.status.HTTP_204_NO_CONTENT,
-            )
+            return drf.response.Response(status=drf.status.HTTP_204_NO_CONTENT)
         return drf.response.Response(
             {"detail": "Document was already not marked as favorite"},
             status=drf.status.HTTP_200_OK,
         )
 
+    @drf.decorators.action(detail=True, methods=["post", "delete"], url_path="mask")
+    def mask(self, request, *args, **kwargs):
+        """Mask or unmask the document for the logged-in user based on the HTTP method."""
+        # Check permissions first
+        document = self.get_object()
+        user = request.user
+
+        try:
+            link_trace = models.LinkTrace.objects.get(document=document, user=user)
+        except models.LinkTrace.DoesNotExist:
+            return drf.response.Response(
+                {"detail": "User never accessed this document before."},
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+
+        if request.method == "POST":
+            if link_trace.is_masked:
+                return drf.response.Response(
+                    {"detail": "Document was already masked"},
+                    status=drf.status.HTTP_200_OK,
+                )
+            link_trace.is_masked = True
+            link_trace.save(update_fields=["is_masked"])
+            return drf.response.Response(
+                {"detail": "Document was masked"},
+                status=drf.status.HTTP_201_CREATED,
+            )
+
+        # Handle DELETE method to unmask document
+        if not link_trace.is_masked:
+            return drf.response.Response(
+                {"detail": "Document was already not masked"},
+                status=drf.status.HTTP_200_OK,
+            )
+        link_trace.is_masked = False
+        link_trace.save(update_fields=["is_masked"])
+        return drf.response.Response(status=drf.status.HTTP_204_NO_CONTENT)
+
     @drf.decorators.action(detail=True, methods=["post"], url_path="attachment-upload")
     def attachment_upload(self, request, *args, **kwargs):
         """Upload a file related to a given document"""

src/backend/core/factories.py

@@ -150,7 +150,7 @@ def link_traces(self, create, extracted, **kwargs):
         """Add link traces to document from a given list of users."""
         if create and extracted:
             for item in extracted:
-                models.LinkTrace.objects.create(document=self, user=item)
+                models.LinkTrace.objects.update_or_create(document=self, user=item)
 
     @factory.post_generation
     def favorited_by(self, create, extracted, **kwargs):
@@ -159,6 +159,15 @@ def favorited_by(self, create, extracted, **kwargs):
             for item in extracted:
                 models.DocumentFavorite.objects.create(document=self, user=item)
 
+    @factory.post_generation
+    def masked_by(self, create, extracted, **kwargs):
+        """Mark document as masked by a list of users."""
+        if create and extracted:
+            for item in extracted:
+                models.LinkTrace.objects.update_or_create(
+                    document=self, user=item, defaults={"is_masked": True}
+                )
+
 
 class UserDocumentAccessFactory(factory.django.DjangoModelFactory):
     """Create fake document user accesses for testing."""

src/backend/core/migrations/0024_add_is_masked_field_to_link_trace.py

@@ -0,0 +1,36 @@
+# Generated by Django 5.2.3 on 2025-07-13 08:22
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("core", "0023_remove_document_is_public_and_more"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="linktrace",
+            name="is_masked",
+            field=models.BooleanField(default=False),
+        ),
+        migrations.AlterField(
+            model_name="user",
+            name="language",
+            field=models.CharField(
+                blank=True,
+                choices=[
+                    ("en-us", "English"),
+                    ("fr-fr", "Français"),
+                    ("de-de", "Deutsch"),
+                    ("nl-nl", "Nederlands"),
+                    ("es-es", "Español"),
+                ],
+                default=None,
+                help_text="The language in which the user wants to see the interface.",
+                max_length=10,
+                null=True,
+                verbose_name="language",
+            ),
+        ),
+    ]

src/backend/core/models.py

@@ -793,6 +793,7 @@ def get_abilities(self, user):
             "favorite": can_get and user.is_authenticated,
             "link_configuration": is_owner_or_admin,
             "invite_owner": is_owner,
+            "mask": can_get and user.is_authenticated,
             "move": is_owner_or_admin and not self.ancestors_deleted_at,
             "partial_update": can_update,
             "restore": is_owner,
@@ -958,6 +959,7 @@ class LinkTrace(BaseModel):
         related_name="link_traces",
     )
     user = models.ForeignKey(User, on_delete=models.CASCADE, related_name="link_traces")
+    is_masked = models.BooleanField(default=False)
 
     class Meta:
         db_table = "impress_link_trace"

src/backend/core/tests/documents/test_api_documents_favorite_list.py

@@ -41,8 +41,8 @@ def test_api_document_favorite_list_authenticated_with_favorite():
     client = APIClient()
     client.force_login(user)
 
-    # User don't have access to this document (e.g the user had access and this
-    # access was removed. It should not be in the favorite list anymore.
+    # If the user doesn't have access to this document (e.g the user had access
+    # and this access was removed), it should not be in the favorite list anymore.
     factories.DocumentFactory(favorited_by=[user])
 
     document = factories.UserDocumentAccessFactory(

src/backend/core/tests/documents/test_api_documents_list_filters.py

@@ -312,6 +312,84 @@ def test_api_documents_list_filter_is_favorite_invalid():
     assert len(results) == 5
 
 
+# Filters: is_masked
+
+
+def test_api_documents_list_filter_is_masked_true():
+    """
+    Authenticated users should be able to filter documents they marked as masked.
+    """
+    user = factories.UserFactory()
+    client = APIClient()
+    client.force_login(user)
+
+    factories.DocumentFactory.create_batch(2, users=[user])
+    masked_documents = factories.DocumentFactory.create_batch(
+        3, users=[user], masked_by=[user]
+    )
+    unmasked_documents = factories.DocumentFactory.create_batch(2, users=[user])
+    for document in unmasked_documents:
+        models.LinkTrace.objects.create(document=document, user=user, is_masked=False)
+
+    response = client.get("/api/v1.0/documents/?is_masked=true")
+
+    assert response.status_code == 200
+    results = response.json()["results"]
+    assert len(results) == 3
+
+    # Ensure all results are marked as masked by the current user
+    masked_documents_ids = [str(doc.id) for doc in masked_documents]
+    for result in results:
+        assert result["id"] in masked_documents_ids
+
+
+def test_api_documents_list_filter_is_masked_false():
+    """
+    Authenticated users should be able to filter documents they didn't mark as masked.
+    """
+    user = factories.UserFactory()
+    client = APIClient()
+    client.force_login(user)
+
+    factories.DocumentFactory.create_batch(2, users=[user])
+    masked_documents = factories.DocumentFactory.create_batch(
+        3, users=[user], masked_by=[user]
+    )
+    unmasked_documents = factories.DocumentFactory.create_batch(2, users=[user])
+    for document in unmasked_documents:
+        models.LinkTrace.objects.create(document=document, user=user, is_masked=False)
+
+    response = client.get("/api/v1.0/documents/?is_masked=false")
+
+    assert response.status_code == 200
+    results = response.json()["results"]
+    assert len(results) == 4
+
+    # Ensure all results are not marked as masked by the current user
+    masked_documents_ids = [str(doc.id) for doc in masked_documents]
+    for result in results:
+        assert result["id"] not in masked_documents_ids
+
+
+def test_api_documents_list_filter_is_masked_invalid():
+    """Filtering with an invalid `is_masked` value should do nothing."""
+    user = factories.UserFactory()
+    client = APIClient()
+    client.force_login(user)
+
+    factories.DocumentFactory.create_batch(2, users=[user])
+    factories.DocumentFactory.create_batch(3, users=[user], masked_by=[user])
+    unmasked_documents = factories.DocumentFactory.create_batch(2, users=[user])
+    for document in unmasked_documents:
+        models.LinkTrace.objects.create(document=document, user=user, is_masked=False)
+
+    response = client.get("/api/v1.0/documents/?is_masked=invalid")
+
+    assert response.status_code == 200
+    results = response.json()["results"]
+    assert len(results) == 7
+
+
 # Filters: title