Table, database and query action menu items now support optional descriptions

datasette/static/app.css

@@ -840,6 +840,13 @@ svg.dropdown-menu-icon {
 .dropdown-menu a:hover {
     background-color: #eee;
 }
+.dropdown-menu .dropdown-description {
+    margin: 0;
+    color: #666;
+    font-size: 0.8em;
+    max-width: 80vw;
+    white-space: normal;
+}
 .dropdown-menu .hook {
     display: block;
     position: absolute;

datasette/templates/database.html

@@ -31,7 +31,11 @@
         {% if links %}
         <ul>
             {% for link in links %}
-            <li><a href="{{ link.href }}">{{ link.label }}</a></li>
+            <li><a href="{{ link.href }}">{{ link.label }}
+            {% if link.description %}
+                <p class="dropdown-description">{{ link.description }}</p>
+            {% endif %}</a>
+            </li>
             {% endfor %}
         </ul>
         {% endif %}

datasette/templates/query.html

@@ -47,7 +47,11 @@
         {% if links %}
         <ul>
             {% for link in links %}
-            <li><a href="{{ link.href }}">{{ link.label }}</a></li>
+            <li><a href="{{ link.href }}">{{ link.label }}
+            {% if link.description %}
+                <p class="dropdown-description">{{ link.description }}</p>
+            {% endif %}</a>
+            </li>
             {% endfor %}
         </ul>
         {% endif %}

datasette/templates/table.html

@@ -42,7 +42,11 @@
         {% if links %}
         <ul>
             {% for link in links %}
-            <li><a href="{{ link.href }}">{{ link.label }}</a></li>
+            <li><a href="{{ link.href }}">{{ link.label }}
+            {% if link.description %}
+                <p class="dropdown-description">{{ link.description }}</p>
+            {% endif %}</a>
+            </li>
             {% endfor %}
         </ul>
         {% endif %}

docs/plugin_hooks.rst

@@ -1493,7 +1493,7 @@ table_actions(datasette, actor, database, table, request)
 ``request`` - :ref:`internals_request` or None
     The current HTTP request. This can be ``None`` if the request object is not available.
 
-This hook allows table actions to be displayed in a menu accessed via an action icon at the top of the table page. It should return a list of ``{"href": "...", "label": "..."}`` menu items.
+This hook allows table actions to be displayed in a menu accessed via an action icon at the top of the table page. It should return a list of ``{"href": "...", "label": "..."}`` menu items, with optional ``"description": "..."`` keys describing each action in more detail.
 
 It can alternatively return an ``async def`` awaitable function which returns a list of menu items.
 
@@ -1515,6 +1515,7 @@ This example adds a new table action if the signed in user is ``"root"``:
                         )
                     ),
                     "label": "Edit schema for this table",
+                    "description": "Add, remove, rename or alter columns for this table."
                 }
             ]
 
@@ -1571,6 +1572,7 @@ This example adds a new query action linking to a page for explaining a query:
                     }
                 ),
                 "label": "Explain this query",
+                "description": "Get a summary of how SQLite executes the query",
             },
         ]
 

tests/plugins/my_plugin.py

@@ -406,6 +406,7 @@ def query_actions(datasette, database, query_name, sql):
                 }
             ),
             "label": "Explain this query",
+            "description": "Runs a SQLite explain",
         },
     ]
 

tests/test_plugins.py

@@ -932,9 +932,9 @@ async def test_hook_table_actions(ds_client, table_or_view):
     assert sorted(
         get_actions_links(response_2.text), key=lambda link: link["label"]
     ) == [
-        {"label": "Database: fixtures", "href": "/"},
-        {"label": "From async BOB", "href": "/"},
-        {"label": f"Table: {table_or_view}", "href": "/"},
+        {"label": "Database: fixtures", "href": "/", "description": None},
+        {"label": "From async BOB", "href": "/", "description": None},
+        {"label": f"Table: {table_or_view}", "href": "/", "description": None},
     ]
 
 
@@ -943,16 +943,16 @@ def get_actions_links(html):
     details = soup.find("details", {"class": "actions-menu-links"})
     if details is None:
         return []
-    return [
-        {
-            "label": a.text.strip(),
-            "href": a["href"],
-            "description": (
-                a.find("p").text.strip() if a.find("p") is not None else None
-            ),
-        }
-        for a in details.select("a")
-    ]
+    links = []
+    for a_el in details.select("a"):
+        description = None
+        if a_el.find("p") is not None:
+            description = a_el.find("p").text.strip()
+            a_el.find("p").extract()
+        label = a_el.text.strip()
+        href = a_el["href"]
+        links.append({"label": label, "href": href, "description": description})
+    return links
 
 
 @pytest.mark.asyncio
@@ -975,7 +975,13 @@ async def test_hook_query_actions(ds_client, path, expected_url):
     if expected_url is None:
         assert links == []
     else:
-        assert links == [{"label": "Explain this query", "href": expected_url}]
+        assert links == [
+            {
+                "label": "Explain this query",
+                "href": expected_url,
+                "description": "Runs a SQLite explain",
+            }
+        ]
 
 
 @pytest.mark.asyncio
@@ -985,7 +991,7 @@ async def test_hook_database_actions(ds_client):
 
     response_2 = await ds_client.get("/fixtures?_bot=1&_hello=BOB")
     assert get_actions_links(response_2.text) == [
-        {"label": "Database: fixtures - BOB", "href": "/"},
+        {"label": "Database: fixtures - BOB", "href": "/", "description": None},
     ]