Replace project and version KO views (#532)

This solves a few issues and explores a pattern that we need to figure
out in
order to replace Knockout views with web components: authoring and
connection
between nested web components. This is a low stakes place to try this.

The issues around the buttons were addressed through adding a click
wrapper to
the link. If you accidentally trigger the link before the API response,
the
click event is stored and re-emitted after the response finishes.

The pattern being explored here is using the web component context API.
This is
implemented in Lit already. You can read more here:

- https://lit.dev/docs/data/context/
-
https://github.com/webcomponents-cg/community-protocols/blob/main/proposals/context.md

So far, we have been trying out manually using events to pass around
data at
a global level. The context API functions similar under the hood, but
the API is
a much cleaner way to pass data around, and it functions only between
parent and
child elements, not globally.

Where this differs from global events is that we can use this pattern
between
parent and child elements, and we don't need to manually search the DOM
for the
parent element:

```html
<readthedocs-api url="...">
  <div>
    <div>
      <div>
        <readthedocs-item-docs>
          This element will traverse up the tree and listen to only the first
          readthedocs-api provider
        </readthedocs-item-docs>
      </div>
    </div>
  </div>
</readthedocs-api url="...">
<readthedocs-api url="...">
  <readthedocs-item-docs>
    And this element will only listen for data provided by that second
    readthedocs-api provider
  </readthedocs-item-docs>
</readthedocs-api>
```

## Why?

We want to author as little as we need to in JS, and as much as we can
in
templates. Using the context API allows us to author isolated web
components
that share data _while still using Django templates for as much of our
page
structure as we can_.

The alternative is authoring everything nested in `readthedocs-api` in a
big
web component, which is not a good pattern for a Django backend.

The work here so far this is a very basic example and the
provider/consumer
elements are close in proximity in the DOM. A more complex example would
be a
table listing, where the table row is a data provider and elements
nested
anywhere in that row element can share data.

We want to keep as much of that row in Django templates as possible,
especially
if that row is 95% vanilla HTML elements and 5% dynamic web components.

----

Things I did not do here:

- Deprecate the older elements using the same base
- Remove old project/version KO views
- Split up code

This will come next.

----

- Fixes #444
- Fixes #497

Author: agjohnson

.prettierignore

@@ -1,7 +1,7 @@
 # Don't do templates at all. Prettier is opinionated and there is extra Django
 # pieces that would be mangled by Prettier.
 *.html
-!/src/js/tests/**/*.html
+/src/js/tests/**/*.html
 /docs/_build/
 /docs/out/
 /build/

package-lock.json

@@ -23,6 +23,8 @@
     "@babel/plugin-proposal-class-properties": "^7.16.7",
     "@babel/plugin-transform-modules-commonjs": "^7.23.0",
     "@babel/preset-env": "^7.22.20",
+    "@lit/context": "^1.1.3",
+    "@lit/localize": "^0.12.2",
     "@open-wc/testing": "^3.2.0",
     "@readthedocs/sui-common-theme": "github:readthedocs/sui-common-theme#12629bb",
     "@rollup/plugin-commonjs": "^25.0.4",

package.json

@@ -34,83 +34,43 @@
   {% endif %}
 {% endblock list_placeholder_text_empty %}
 
-{% block list_item_start %}
-  {# This confuses the formatter as it's just an opening element #}
-  {# djlint: off #}
-  <tr class="middle aligned"
-      data-bind="using: VersionListItemView({id: {{ object.pk }}, url: '{% url "projects-versions-detail" object.project.slug object.slug %}'})">
-  {# djlint: on #}
-{% endblock list_item_start %}
-
 {% block list_item_right_menu %}
-  <div class="ui small icon buttons">
-
-    {% blocktrans trimmed with version=object.verbose_name asvar label_link %}
-      View documentation for version {{ version }}
-    {% endblocktrans %}
-    <a class="ui {% if not object.built %}disabled{% endif %} button"
-       data-bind="event: {mouseover: fetch, focusin: fetch}, attr: {href: url_docs}"
-       target="_blank"
-       data-content="{{ label_link }}"
-       aria-label="{{ label_link }}"
-       tabindex="{% if object.built %}0{% else %}-1{% endif %}">
-      <i class="fa-solid fa-book icon"></i>
-    </a>
-
-    {% blocktrans trimmed with version=object.verbose_name asvar label_download %}
-      Offline formats for version {{ version }}
-    {% endblocktrans %}
-    <button class="ui {% if not object.has_epub and not object.has_htmlzip and not object.has_pdf %} disabled{% endif %} dropdown button"
-            data-bind="event: {focusin: fetch, click: fetch}"
-            data-content="{{ label_download }}"
-            aria-label="{{ label_download }}"
-            tabindex="{% if object.has_epub or object.has_htmlzip or object.has_pdf %}0{% else %}-1{% endif %}">
-      <i class="fa-solid fa-download icon"></i>
-      <div class="menu">
-        <div class="header">{% trans "Offline formats" %}</div>
-        <a class="disabled item"
-           data-bind="css: {disabled: !url_pdf()}, attr: {href: url_pdf()}">
-          <i class="fa-duotone fa-file icon"></i>
-          {% trans "PDF file" %}
-        </a>
-        <a class="disabled item"
-           data-bind="css: {disabled: !url_epub()}, attr: {href: url_epub()}">
-          <i class="fa-duotone fa-file icon"></i>
-          {% trans "ePUB file" %}
-        </a>
-        <a class="disabled item"
-           data-bind="css: {disabled: !url_html()}, attr: {href: url_html()}">
-          <i class="fa-duotone fa-file-zipper icon"></i>
-          {% trans "HTML archive" %}
-        </a>
-      </div>
-    </button>
-
-    {% blocktrans trimmed with version=object.verbose_name asvar label_admin %}
-      Additional options for version {{ version }}
-    {% endblocktrans %}
-    {% if is_project_admin %}
-      <div class="ui dropdown button"
-           data-content="{{ label_admin }}"
-           aria-label="{{ label_admin }}">
-        <i class="fa-solid fa-ellipsis icon"></i>
-        <div class="menu">
-          <div class="header">{% trans "Admin" %}</div>
-          <readthedocs-menu-build-rebuild class="item"
-                                          url="{% url "projects-versions-builds-list" object.project.slug object.slug %}"
-                                          csrf-token="{{ csrf_token }}">
-            <i class="fa-duotone fa-refresh icon"></i>
-            {% trans "Rebuild version" %}
-          </readthedocs-menu-build-rebuild>
-          <a class="item"
-             href="{% url "project_version_detail" project.slug object.slug %}">
-            <i class="fa-duotone fa-wrench icon"></i>
-            {% trans "Configure version" %}
-          </a>
+  <readthedocs-api csrf-token="{{ csrf_token }}"
+                   url="{% url "projects-versions-detail" object.project.slug object.slug %}">
+    <div class="ui small icon buttons">
+      <readthedocs-item-docs {% if not object.built %}disabled{% endif %}
+                             label="{% blocktrans with name=object.verbose_name %}View documentation for version {{ name }}{% endblocktrans %}">
+      </readthedocs-item-docs>
+      <readthedocs-item-downloads {% if not object.has_pdf and not object.has_epub and not object.has_htmlzip %}disabled{% endif %}
+                                  label="{% blocktrans with name=object.verbose_name %}Offline formats for version {{ name }}{% endblocktrans %}">
+      </readthedocs-item-downloads>
+
+      {% blocktrans trimmed with name=object.verbose_name asvar label_admin %}
+        Additional options for version {{ name }}
+      {% endblocktrans %}
+      {% if is_project_admin %}
+        <div class="ui dropdown button"
+             data-content="{{ label_admin }}"
+             aria-label="{{ label_admin }}">
+          <i class="fa-solid fa-ellipsis icon"></i>
+          <div class="menu">
+            <div class="header">{% trans "Admin" %}</div>
+            <readthedocs-menu-build-rebuild class="item"
+                                            url="{% url "projects-versions-builds-list" object.project.slug object.slug %}"
+                                            csrf-token="{{ csrf_token }}">
+              <i class="fa-duotone fa-refresh icon"></i>
+              {% trans "Rebuild version" %}
+            </readthedocs-menu-build-rebuild>
+            <a class="item"
+               href="{% url "project_version_detail" project.slug object.slug %}">
+              <i class="fa-duotone fa-wrench icon"></i>
+              {% trans "Configure version" %}
+            </a>
+          </div>
         </div>
-      </div>
-    {% endif %}
-  </div>
+      {% endif %}
+    </div>
+  </readthedocs-api>
 {% endblock list_item_right_menu %}
 
 {% block list_item_icon %}

readthedocsext/theme/static/readthedocsext/theme/css/site.css

@@ -1,15 +1,9 @@
 {% extends "projects/partials/project_list.html" %}
 
-{% load i18n %}
+{% load blocktrans from i18n %}
 
 {# TODO drop this override if we add filtering to the profile page #}
 {% block top_menu %}
-  {# Pass Django template tag specific configuration into ``ProjectListView`` #}
-  <script type="application/json" data-bind="jsonInit: config">
-    {
-      "api_url": "{% url "projects-list" %}"
-    }
-  </script>
 {% endblock top_menu %}
 
 {% block create_button %}

readthedocsext/theme/static/readthedocsext/theme/js/site.js

@@ -29,41 +29,20 @@
      class="ui primary button">{% trans "Learn how to get started" %}</a>
 {% endblock list_placeholder_text_empty %}
 
-{% block list_item_start %}
-  {# djlint:off #}
-  <tr data-bind="using: ProjectListItemView({id: {{ object.id }}, url: '{% url "projects-detail" object.slug %}'})">
-  {# djlint:on #}
-{% endblock list_item_start %}
-
 {% block list_item_right_menu %}
-  <div class="ui small icon buttons"
-       data-bind="event: {mouseover: fetch, focusin: fetch}">
-    {% blocktrans trimmed with project=object.name asvar label_link %}
-      View documentation for project {{ project }}
-    {% endblocktrans %}
-    <a class="ui {% if not object.has_good_build %}disabled{% endif %} button"
-       data-content="{{ label_link }}"
-       aria-label="{{ label_link }}"
-       data-bind="attr: {href: url_docs}"
-       target="_blank"
-       tabindex="{% if object.has_good_build %}0{% else %}-1{% endif %}">
-      <i class="fa-duotone fa-book icon"></i>
-    </a>
-
-    <button class="ui dropdown button">
-      <i class="fa-solid fa-ellipsis icon"></i>
-      <div class="menu">
-        <div class="header">{% trans "Admin" %}</div>
-        <a class="disabled item"
-           href="{% url "projects_edit" object.slug %}"
-           data-bind="css: { disabled: !is_admin() }">
-          <i class="fa-duotone fa-wrench icon"></i>
-          {% trans "Configure project" %}
-        </a>
-      </div>
-    </button>
-
-  </div>
+  <readthedocs-api csrf-token="{{ csrf_token }}"
+                   url="{% url "projects-detail" object.slug %}?expand=permissions">
+    <div class="ui small icon buttons">
+      <readthedocs-item-docs {% if not object.has_good_build %}disabled{% endif %}
+                             label="{% blocktrans with name=object.name %}View documentation for project {{ name }}{% endblocktrans %}">
+      </readthedocs-item-docs>
+      <button class="ui dropdown button">
+        <i class="fa-solid fa-ellipsis icon"></i>
+        <readthedocs-menu-project-admin class="menu" url-settings="{% url "projects_edit" object.slug %}">
+        </readthedocs-menu-project-admin>
+      </button>
+    </div>
+  </readthedocs-api>
 {% endblock list_item_right_menu %}
 
 {% block list_item_image %}