Use form validation errors for important UI feedback (#11095)

* Add base classes for prevalidation Form and rich validation errors

- Prevalidaition on forms allows throwing errors on the initial form
  display, before the user submits the form.
- Rich validation errors gives non-field error message types (info,
  error, warning, etc) and header/title text

* Refactor project create form to use form validation errors

Instead of using notifications without a database, use form validation
errors to raise error states on specific forms, or outright disable
them.

* Add logic for team, owner, and SSO validations

* Invert conditional to avoid `not any()`

* Clarify some of the prevalidation form internals

* Fix is_valid call

* Fix not implemented throw

* Add tests for form prevalidation

* Pytest tests -> unittest tests

Author: agjohnson

readthedocs/core/forms.py

@@ -5,6 +5,7 @@
 from crispy_forms.layout import Fieldset, Layout, Submit
 from django import forms
 from django.contrib.auth.models import User
+from django.core.exceptions import NON_FIELD_ERRORS
 from django.forms.fields import CharField
 from django.utils.translation import gettext_lazy as _
 
@@ -98,6 +99,96 @@ class Meta:
         fields = ["allow_ads"]
 
 
+class PrevalidatedForm(forms.Form):
+
+    """
+    Form class that allows raising form errors before form submission.
+
+    The base ``Form`` does not support validation errors while the form is
+    unbound (does not have ``data`` defined). There are cases in our UI where we
+    want to show errors and/or disabled the form before the user has a chance to
+    interact with the form -- for example, when a feature is unavailable or
+    disabled for the user or organization.
+
+    This provides the ``clean_prevalidation`` method, which acts much like the
+    ``clean`` method. Any validation errors raised in this method surface as non
+    field errors in the UI.
+    """
+
+    def __init__(self, *args, **kwargs):
+        self._prevalidation_errors = None
+        super().__init__(*args, **kwargs)
+
+    def is_valid(self):
+        # This differs from ``Form`` in that we don't care if the form is bound
+        return not self.errors
+
+    @property
+    def is_disabled(self):
+        return self._prevalidation_errors is not None
+
+    def full_clean(self):
+        """
+        Extend full clean method with prevalidation cleaning.
+
+        Where :py:method:`forms.Form.full_clean` bails out if there is no bound
+        data on the form, this method always checks prevalidation no matter
+        what. This gives errors before submission and after submission.
+        """
+        # Always call prevalidation, ``full_clean`` bails if the form is unbound
+        self._clean_prevalidation()
+
+        super().full_clean()
+
+        # ``full_clean`` sets ``self._errors``, so we prepend prevalidation
+        # errors after calling the parent ``full_clean``
+        if self._prevalidation_errors is not None:
+            non_field_errors = []
+            non_field_errors.extend(self._prevalidation_errors)
+            non_field_errors.extend(self._errors.get(NON_FIELD_ERRORS, []))
+            self._errors[NON_FIELD_ERRORS] = non_field_errors
+
+    def _clean_prevalidation(self):
+        """
+        Catch validation errors raised by the subclassed ``clean_validation()``.
+
+        This wraps ``clean_prevalidation()`` using the same pattern that
+        :py:method:`form.Form._clean_form` wraps :py:method:`clean`. Validation
+        errors raised in the subclass method will be eventually added to the
+        form error list but :py:method:`full_clean`.
+        """
+        try:
+            self.clean_prevalidation()
+        except forms.ValidationError as validation_error:
+            self._prevalidation_errors = [validation_error]
+
+    def clean_prevalidation(self):
+        raise NotImplementedError()
+
+
+class RichValidationError(forms.ValidationError):
+
+    """
+    Show non-field form errors as titled messages.
+
+    This uses more of the FUI message specification to give a really clear,
+    concise error message to the user. Without this class, non-field validation
+    errors show at the top of the form with a title "Error", which isn't as
+    helpful to users as something like "Connected service required".
+
+    :param header str: Message header/title text
+    :param message_class str: FUI CSS class to use on the message -- "info",
+        etc. Default: "error".
+    """
+
+    def __init__(
+        self, message, code=None, params=None, header=None, message_class=None
+    ):
+        super().__init__(message, code, params)
+        self.header = header
+        self.message_class = message_class
+
+
 class FacetField(forms.MultipleChoiceField):
 
     """

readthedocs/projects/forms.py

@@ -4,6 +4,7 @@
 from re import fullmatch
 from urllib.parse import urlparse
 
+from allauth.socialaccount.models import SocialAccount
 from django import forms
 from django.conf import settings
 from django.contrib.auth.models import User
@@ -12,12 +13,15 @@
 from django.utils.translation import gettext_lazy as _
 
 from readthedocs.builds.constants import INTERNAL
+from readthedocs.core.forms import PrevalidatedForm, RichValidationError
 from readthedocs.core.history import SimpleHistoryModelForm
+from readthedocs.core.permissions import AdminPermission
 from readthedocs.core.utils import slugify, trigger_build
 from readthedocs.core.utils.extend import SettingsOverrideObject
 from readthedocs.integrations.models import Integration
 from readthedocs.invitations.models import Invitation
 from readthedocs.oauth.models import RemoteRepository
+from readthedocs.organizations.models import Team
 from readthedocs.projects.models import (
     AddonsConfig,
     Domain,
@@ -78,6 +82,112 @@ class ProjectBackendForm(forms.Form):
     backend = forms.CharField()
 
 
+class ProjectFormPrevalidateMixin:
+
+    """Provides shared logic between the automatic and manual create forms."""
+
+    def __init__(self, *args, **kwargs):
+        self.user = kwargs.pop("user", None)
+        super().__init__(*args, **kwargs)
+
+    def clean_prevalidation(self):
+        # Shared conditionals between automatic and manual forms
+        self.user_has_connected_account = SocialAccount.objects.filter(
+            user=self.user,
+        ).exists()
+        self.user_is_nonowner_with_sso = None
+        self.user_missing_admin_permission = None
+        if settings.RTD_ALLOW_ORGANIZATIONS:
+            # TODO there should be some way to initially select the organization
+            # and maybe the team too. It's mostly safe to automatically select
+            # the first organization, but explicit would be better. Reusing the
+            # organization selection UI works, we only really need a query param
+            # here.
+            self.user_is_nonowner_with_sso = all(
+                [
+                    AdminPermission.has_sso_enabled(self.user),
+                    AdminPermission.organizations(
+                        user=self.user,
+                        owner=False,
+                    ).exists(),
+                ]
+            )
+
+            # TODO this logic should be possible from AdminPermission
+            # AdminPermssion.is_admin only inspects organization owners, so the
+            # additional team check is necessary
+            self.user_has_admin_permission = any(
+                [
+                    AdminPermission.organizations(
+                        user=self.user,
+                        owner=True,
+                    ).exists(),
+                    Team.objects.admin(self.user).exists(),
+                ]
+            )
+
+
+class ProjectAutomaticForm(ProjectFormPrevalidateMixin, PrevalidatedForm):
+    def clean_prevalidation(self):
+        """
+        Block user from using this form for important blocking states.
+
+        We know before the user gets a chance to use this form that the user
+        might not have the ability to add a project into their organization.
+        These errors are raised before the user submits the form.
+        """
+        super().clean_prevalidation()
+        if not self.user_has_connected_account:
+            url = reverse("socialaccount_connections")
+            raise RichValidationError(
+                _(
+                    f"You must first <a href='{url}'>add a connected service "
+                    f"to your account</a> to enable automatic configuration of "
+                    f"repositories."
+                ),
+                header=_("No connected services found"),
+            )
+        if settings.RTD_ALLOW_ORGANIZATIONS:
+            if self.user_is_nonowner_with_sso:
+                raise RichValidationError(
+                    _(
+                        "Only organization owners may create new projects "
+                        "when single sign-on is enabled."
+                    ),
+                    header=_("Organization single sign-on enabled"),
+                )
+            if not self.user_has_admin_permission:
+                raise RichValidationError(
+                    _(
+                        "You must be on a team with admin permissions "
+                        "in order to add a new project to your organization."
+                    ),
+                    header=_("Admin permission required"),
+                )
+
+
+class ProjectManualForm(ProjectFormPrevalidateMixin, PrevalidatedForm):
+    def clean_prevalidation(self):
+        super().clean_prevalidation()
+        if settings.RTD_ALLOW_ORGANIZATIONS:
+            if self.user_is_nonowner_with_sso:
+                raise RichValidationError(
+                    _(
+                        "Projects cannot be manually configured when "
+                        "single sign-on is enabled for your organization."
+                    ),
+                    header=_("Organization single sign-on enabled"),
+                )
+            if not self.user_has_admin_permission:
+                raise RichValidationError(
+                    _(
+                        "You must be on a team with admin permissions "
+                        "in order to add a new project to your organization."
+                    ),
+                    header=_("Admin permission required"),
+                )
+
+
 class ProjectBasicsForm(ProjectForm):
 
     """Form for basic project fields."""

readthedocs/projects/views/private.py

@@ -55,8 +55,10 @@
     IntegrationForm,
     ProjectAdvancedForm,
     ProjectAdvertisingForm,
+    ProjectAutomaticForm,
     ProjectBasicsForm,
     ProjectConfigForm,
+    ProjectManualForm,
     ProjectRelationshipForm,
     RedirectForm,
     TranslationForm,
@@ -397,9 +399,11 @@ def post(self, request, *args, **kwargs):
     def get_context_data(self, **kwargs):
         context = super().get_context_data(**kwargs)
         context['view_csrf_token'] = get_token(self.request)
-        context['has_connected_accounts'] = SocialAccount.objects.filter(
-            user=self.request.user,
-        ).exists()
+
+        if settings.RTD_EXT_THEME_ENABLED:
+            context["form_automatic"] = ProjectAutomaticForm(user=self.request.user)
+            context["form_manual"] = ProjectManualForm(user=self.request.user)
+
         return context