✨(backend) give an order to choices

We are going to need to compare choices to materialize the fact that
choices are ordered. For example an admin role is higer than an
editor role but lower than an owner role.

We will need this to compute the reach and role resulting from all
the document accesses (resp. link accesses) assigned on a document's
ancestors.

src/backend/core/choices.py

@@ -0,0 +1,123 @@
+"""Declare and configure choices for Docs' core application."""
+
+from django.db.models import TextChoices
+from django.utils.translation import gettext_lazy as _
+
+
+class PriorityTextChoices(TextChoices):
+    """
+    This class inherits from Django's TextChoices and provides a method to get the priority
+    of a given value based on its position in the class.
+    """
+
+    @classmethod
+    def get_priority(cls, value):
+        """Returns the priority of the given value based on its order in the class."""
+        members = list(cls.__members__.values())
+        return members.index(value) + 1 if value in members else 0
+
+    @classmethod
+    def max(cls, *roles):
+        """
+        Return the highest-priority role among the given roles, using get_priority().
+        If no valid roles are provided, returns None.
+        """
+
+        valid_roles = [role for role in roles if cls.get_priority(role) is not None]
+        if not valid_roles:
+            return None
+        return max(valid_roles, key=cls.get_priority)
+
+
+class LinkRoleChoices(PriorityTextChoices):
+    """Defines the possible roles a link can offer on a document."""
+
+    READER = "reader", _("Reader")  # Can read
+    EDITOR = "editor", _("Editor")  # Can read and edit
+
+
+class RoleChoices(PriorityTextChoices):
+    """Defines the possible roles a user can have in a resource."""
+
+    READER = "reader", _("Reader")  # Can read
+    EDITOR = "editor", _("Editor")  # Can read and edit
+    ADMIN = "administrator", _("Administrator")  # Can read, edit, delete and share
+    OWNER = "owner", _("Owner")
+
+
+PRIVILEGED_ROLES = [RoleChoices.ADMIN, RoleChoices.OWNER]
+
+
+class LinkReachChoices(PriorityTextChoices):
+    """Defines types of access for links"""
+
+    RESTRICTED = (
+        "restricted",
+        _("Restricted"),
+    )  # Only users with a specific access can read/edit the document
+    AUTHENTICATED = (
+        "authenticated",
+        _("Authenticated"),
+    )  # Any authenticated user can access the document
+    PUBLIC = "public", _("Public")  # Even anonymous users can access the document
+
+    @classmethod
+    def get_select_options(cls, ancestors_links):
+        """
+        Determines the valid select options for link reach and link role depending on the
+        list of ancestors' link reach/role.
+        Args:
+            ancestors_links: List of dictionaries, each with 'link_reach' and 'link_role' keys
+                             representing the reach and role of ancestors links.
+        Returns:
+            Dictionary mapping possible reach levels to their corresponding possible roles.
+        """
+        # If no ancestors, return all options
+        if not ancestors_links:
+            return {
+                reach: LinkRoleChoices.values if reach != cls.RESTRICTED else None
+                for reach in cls.values
+            }
+
+        # Initialize result with all possible reaches and role options as sets
+        result = {
+            reach: set(LinkRoleChoices.values) if reach != cls.RESTRICTED else None
+            for reach in cls.values
+        }
+
+        # Group roles by reach level
+        reach_roles = defaultdict(set)
+        for link in ancestors_links:
+            reach_roles[link["link_reach"]].add(link["link_role"])
+
+        # Rule 1: public/editor → override everything
+        if LinkRoleChoices.EDITOR in reach_roles.get(cls.PUBLIC, set()):
+            return {cls.PUBLIC: [LinkRoleChoices.EDITOR]}
+
+        # Rule 2: authenticated/editor
+        if LinkRoleChoices.EDITOR in reach_roles.get(cls.AUTHENTICATED, set()):
+            result[cls.AUTHENTICATED].discard(LinkRoleChoices.READER)
+            result.pop(cls.RESTRICTED, None)
+
+        # Rule 3: public/reader
+        if LinkRoleChoices.READER in reach_roles.get(cls.PUBLIC, set()):
+            result.pop(cls.AUTHENTICATED, None)
+            result.pop(cls.RESTRICTED, None)
+
+        # Rule 4: authenticated/reader
+        if LinkRoleChoices.READER in reach_roles.get(cls.AUTHENTICATED, set()):
+            result.pop(cls.RESTRICTED, None)
+
+        # Clean up: remove empty entries and convert sets to ordered lists
+        cleaned = {}
+        for reach in cls.values:
+            if reach in result:
+                if result[reach]:
+                    cleaned[reach] = [
+                        r for r in LinkRoleChoices.values if r in result[reach]
+                    ]
+                else:
+                    # Could be [] or None (for RESTRICTED reach)
+                    cleaned[reach] = result[reach]
+
+        return cleaned