wagtail-developer-reference 0.1.3__tar.gz → 0.1.4__tar.gz

{wagtail_developer_reference-0.1.3/wagtail_developer_reference.egg-info → wagtail_developer_reference-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wagtail-developer-reference
-Version: 0.1.3
+Version: 0.1.4
 Summary: A visual auditing tool for Wagtail developers to track Page models and StreamField blocks.
 Author-email: Four Digits <info@fourdigits.nl>
 Project-URL: Homepage, https://github.com/fourdigits/wagtail-developer-reference
@@ -32,16 +32,18 @@ Requires-Dist: pytest-django; extra == "dev"
 In large Wagtail projects, it’s easy to lose track of where specific blocks are used or which templates are being rendered. This tool gives you a "God-view" of your components without needing to dig through the database or shell.
 
 ## Features
-* **On-demand usage tracking:** Apply filters before calculating page and block usage, keeping the registry quick to open.
-* **Interactive registry:** Combine text, PAGE/BLOCK, site and total-usage-range filters to find exactly the components you need.
-* **Nested block discovery:** Browse visible block labels and full nested definition paths, with safe fallbacks for unlabeled blocks.
-* **Usage inspection:** Search and paginate matching pages, then copy the visible usage table in one click.
+* **Fast registry:** Code definitions are cached per worker; the normal registry response stays small and paginates at 20 rows.
+* **On-demand exact usage:** PAGE and BLOCK counts are calculated only for a usage range, scoped to the exact page model, StreamField and nested definition path.
+* **Scalable StreamField inspection:** Usage scans read raw StreamField JSON, avoiding chooser-object queries while keeping totals current.
+* **Searchable block picker:** An accessible, collapsed picker searches all definitions server-side and returns at most 30 choices at once.
+* **Multi-site aware:** Site root pages are included, nested subsites are excluded from parent-site counts, and an empty site filter aggregates globally.
+* **Usage inspection:** Open an exact definition's paginated page list and copy the visible usage table in one click.
 * **Template discovery:** See the template path associated with every component.
 
 ## Installation
 
-Compatibility: Python 3.9+ and Wagtail 4.1 through 7.4.2 LTS (the latest
-stable Wagtail release at v0.1.3). Wagtail 7.4 itself requires Python 3.10+.
+Compatibility: Python 3.9+ and Wagtail 4.1 through 7.4.2 LTS. Wagtail 7.4
+itself requires Python 3.10+.
 
 1. Add \`wagtail_developer_reference\` to your \`INSTALLED_APPS\`:
    \`\`\`python

{wagtail_developer_reference-0.1.3 → wagtail_developer_reference-0.1.4}/README.md

@@ -6,16 +6,18 @@
 In large Wagtail projects, it’s easy to lose track of where specific blocks are used or which templates are being rendered. This tool gives you a "God-view" of your components without needing to dig through the database or shell.
 
 ## Features
-* **On-demand usage tracking:** Apply filters before calculating page and block usage, keeping the registry quick to open.
-* **Interactive registry:** Combine text, PAGE/BLOCK, site and total-usage-range filters to find exactly the components you need.
-* **Nested block discovery:** Browse visible block labels and full nested definition paths, with safe fallbacks for unlabeled blocks.
-* **Usage inspection:** Search and paginate matching pages, then copy the visible usage table in one click.
+* **Fast registry:** Code definitions are cached per worker; the normal registry response stays small and paginates at 20 rows.
+* **On-demand exact usage:** PAGE and BLOCK counts are calculated only for a usage range, scoped to the exact page model, StreamField and nested definition path.
+* **Scalable StreamField inspection:** Usage scans read raw StreamField JSON, avoiding chooser-object queries while keeping totals current.
+* **Searchable block picker:** An accessible, collapsed picker searches all definitions server-side and returns at most 30 choices at once.
+* **Multi-site aware:** Site root pages are included, nested subsites are excluded from parent-site counts, and an empty site filter aggregates globally.
+* **Usage inspection:** Open an exact definition's paginated page list and copy the visible usage table in one click.
 * **Template discovery:** See the template path associated with every component.
 
 ## Installation
 
-Compatibility: Python 3.9+ and Wagtail 4.1 through 7.4.2 LTS (the latest
-stable Wagtail release at v0.1.3). Wagtail 7.4 itself requires Python 3.10+.
+Compatibility: Python 3.9+ and Wagtail 4.1 through 7.4.2 LTS. Wagtail 7.4
+itself requires Python 3.10+.
 
 1. Add \`wagtail_developer_reference\` to your \`INSTALLED_APPS\`:
    \`\`\`python

{wagtail_developer_reference-0.1.3 → wagtail_developer_reference-0.1.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "wagtail-developer-reference"
-version = "0.1.3"
+version = "0.1.4"
 description = "A visual auditing tool for Wagtail developers to track Page models and StreamField blocks."
 readme = "README.md"
 authors = [{name = "Four Digits", email = "info@fourdigits.nl" }]

{wagtail_developer_reference-0.1.3 → wagtail_developer_reference-0.1.4}/setup.py

@@ -2,7 +2,7 @@ from setuptools import find_packages, setup
 
 setup(
     name="wagtail-developer-reference",
-    version="0.1.3",
+    version="0.1.4",
     packages=find_packages(),
     include_package_data=True,
     install_requires=[

{wagtail_developer_reference-0.1.3 → wagtail_developer_reference-0.1.4}/wagtail_developer_reference/templates/detail.html

@@ -129,7 +129,7 @@
       <div class="breadcrumb">
         <a href="{% url 'dev_reference' %}">&larr; Back to System Registry</a>
       </div>
-      <h1>Locations for: <strong>{{ component_name }}</strong></h1>
+      <h1>Usage: <strong>{{ component_name }}</strong></h1>
       <p>{{ page_obj.paginator.count }} location{{ page_obj.paginator.count|pluralize }} found</p>
     </div>
   </header>
@@ -159,14 +159,14 @@
           <tr class="usage-row">
             <td>
               <strong class="page-title">{{ page.title }}</strong>
-              <small class="page-type">Type: {{ page.get_verbose_name }}</small>
+              <small class="page-type">Type: {{ page.content_type.name|title }}</small>
             </td>
             <td class="td-status" data-sort="{% if page.live %}1{% else %}0{% endif %}">
               <span class="status-tag status-tag--{% if page.live %}live{% else %}draft{% endif %}">
                 {% if page.live %}Live{% else %}Draft{% endif %}
               </span>
             </td>
-            <td><code class="url-code">{{ page.url|default:"/(no slug)/" }}</code></td>
+            <td><code class="url-code">{{ page.url_path|default:"/(no path)/" }}</code></td>
             <td class="col-actions">
               <a href="{% url 'wagtailadmin_pages:edit' page.id %}" class="button button-small edit-button" target="_blank">Edit Page</a>
             </td>

{wagtail_developer_reference-0.1.3 → wagtail_developer_reference-0.1.4}/wagtail_developer_reference/templates/index.html

@@ -120,15 +120,16 @@
             <input id="quick-search-filter" class="quick-search-filter" type="search" placeholder="Search pages and blocks..." autocomplete="off">
             <span id="quick-search-status" class="quick-search-status" aria-live="polite"></span>
             <div class="quick-search-list" aria-label="Quick registry search">
-                {% for component_type, component_name, display_name in quick_search_items %}
-                    <button type="button" class="quick-search-item" data-search="{{ component_name }}" data-type="{{ component_type }}" data-quick-search="{{ component_name }} {{ display_name }}" data-quick-index="{{ forloop.counter0 }}">
-                        <span class="type-tag type-tag--{{ component_type|lower }}">{{ component_type }}</span>{{ display_name }}
+                {% for item in quick_search_items %}
+                    <button type="button" class="quick-search-item" data-search="{{ item.hierarchy }}" data-type="{{ item.component_type }}" data-definition="{{ item.definition_id }}">
+                        <span class="type-tag type-tag--{{ item.component_type|lower }}">{{ item.component_type }}</span>{{ item.hierarchy }}
                     </button>
                 {% endfor %}
             </div>
         </details>
         <form id="registry-filter-form" method="get" class="registry-controls">
             <input type="hidden" name="apply" value="1">
+            <input id="definition-filter" type="hidden" name="definition" value="{{ filters.definition }}">
             <div class="registry-search"><label for="reg-search">Search Registry</label><input type="search" id="reg-search" name="q" value="{{ filters.q }}" placeholder="Name, field or site..."></div>
             <div><label for="reg-filter">Component Type</label><select id="reg-filter" name="type"><option value="ALL" {% if filters.type == "ALL" %}selected{% endif %}>All</option><option value="PAGE" {% if filters.type == "PAGE" %}selected{% endif %}>Pages</option><option value="BLOCK" {% if filters.type == "BLOCK" %}selected{% endif %}>Blocks</option></select></div>
             <div><label for="reg-site-filter">Site</label><select id="reg-site-filter" name="site"><option value="">All sites</option>{% for site in sites %}<option value="{{ site.id }}" {% if filters.site == site.id|stringformat:"s" %}selected{% endif %}>{{ site.site_name }}</option>{% endfor %}</select></div>
@@ -179,21 +180,15 @@
                             {% endfor %}
                         </div>
                     </td>
-                    <td class="col-centered" data-sort="{{ item.usage.draft }}">
-                        <span class="{% if item.usage.draft > 0 %}count-draft{% else %}zero-usage{% endif %}">{{ item.usage.draft }}</span>
-                    </td>
-                    <td class="col-centered" data-sort="{{ item.usage.live }}">
-                        <span class="{% if item.usage.live > 0 %}count-live{% else %}zero-usage{% endif %}">{{ item.usage.live }}</span>
-                    </td>
-                    <td class="col-centered" data-sort="{{ item.usage.total }}">
-                        {% if item.usage.total > 0 %}
-                            <a href="{% url 'dev_usage_detail' item.type item.clean_name %}?site={{ item.site_id }}" class="button button-small usage-link">
-                                {{ item.usage.total }}
-                            </a>
-                        {% else %}
-                            <span class="zero-usage">0</span>
-                        {% endif %}
-                    </td>
+                    {% if usage_requested %}
+                        <td class="col-centered" data-sort="{{ item.usage.draft }}"><span class="{% if item.usage.draft > 0 %}count-draft{% else %}zero-usage{% endif %}">{{ item.usage.draft }}</span></td>
+                        <td class="col-centered" data-sort="{{ item.usage.live }}"><span class="{% if item.usage.live > 0 %}count-live{% else %}zero-usage{% endif %}">{{ item.usage.live }}</span></td>
+                        <td class="col-centered" data-sort="{{ item.usage.total }}">{% if item.usage.total > 0 %}<a href="{% url 'dev_definition_usage' item.definition_id %}{% if item.site_id %}?site={{ item.site_id }}{% endif %}" class="button button-small usage-link">{{ item.usage.total }}</a>{% else %}<span class="zero-usage">0</span>{% endif %}</td>
+                    {% else %}
+                        <td class="col-centered"><span class="template-empty">—</span></td>
+                        <td class="col-centered"><span class="template-empty">—</span></td>
+                        <td class="col-centered"><span class="template-empty">Add min or max</span></td>
+                    {% endif %}
                     <td>
                         {% if item.template %}
                             <span class="template-label" title="{{ item.template }}">{{ item.template_label }}</span>
@@ -206,6 +201,13 @@
                 {% endfor %}
             </tbody>
         </table>
+        {% if page_obj.paginator.num_pages > 1 %}
+            <nav class="pagination" aria-label="Registry result pages">
+                {% if page_obj.has_previous %}<a class="button" href="?apply=1&amp;q={{ filters.q|urlencode }}&amp;type={{ filters.type|urlencode }}&amp;site={{ filters.site|urlencode }}&amp;min_usage={{ filters.min_usage|urlencode }}&amp;max_usage={{ filters.max_usage|urlencode }}&amp;definition={{ filters.definition|urlencode }}&amp;page={{ page_obj.previous_page_number }}">Previous</a>{% endif %}
+                <span>Page {{ page_obj.number }} of {{ page_obj.paginator.num_pages }} ({{ page_obj.paginator.count }} results)</span>
+                {% if page_obj.has_next %}<a class="button" href="?apply=1&amp;q={{ filters.q|urlencode }}&amp;type={{ filters.type|urlencode }}&amp;site={{ filters.site|urlencode }}&amp;min_usage={{ filters.min_usage|urlencode }}&amp;max_usage={{ filters.max_usage|urlencode }}&amp;definition={{ filters.definition|urlencode }}&amp;page={{ page_obj.next_page_number }}">Next</a>{% endif %}
+            </nav>
+        {% endif %}
         {% else %}
             <p class="help-block">Choose filters and select <strong>Apply Filters</strong> to load registry usage.</p>
         {% endif %}
@@ -273,41 +275,76 @@
 
         const quickSearchInput = document.getElementById("quick-search-filter");
         const quickSearchStatus = document.getElementById("quick-search-status");
-        const quickSearchItems = Array.from(document.querySelectorAll(".quick-search-item"));
-        const initialQuickSearchLimit = 30;
+        const quickSearchList = document.querySelector(".quick-search-list");
+        const definitionFilter = document.getElementById("definition-filter");
+        let quickSearchTimer;
+        let quickSearchController;
+
+        function selectQuickItem(button) {
+            document.getElementById("reg-search").value = button.dataset.search;
+            document.getElementById("reg-filter").value = button.dataset.type;
+            definitionFilter.value = button.dataset.definition;
+            document.getElementById("registry-filter-form").submit();
+        }
 
-        function runQuickSearch() {
-            const query = quickSearchInput.value.trim().toLowerCase();
-            let matches = 0;
-            quickSearchItems.forEach(button => {
-                const matchesQuery = button.dataset.quickSearch.toLowerCase().includes(query);
-                const withinInitialLimit = query || Number(button.dataset.quickIndex) < initialQuickSearchLimit;
-                const isVisible = matchesQuery && withinInitialLimit;
-                button.hidden = !isVisible;
-                if (matchesQuery) matches += 1;
+        function bindQuickItems() {
+            quickSearchList.querySelectorAll(".quick-search-item").forEach(button => {
+                button.addEventListener("click", () => selectQuickItem(button));
             });
-            quickSearchStatus.textContent = query
-                ? `${matches} matching component${matches === 1 ? "" : "s"}`
-                : `Showing the first ${Math.min(initialQuickSearchLimit, matches)} of ${matches} components. Type to narrow the list.`;
         }
 
-        document.querySelectorAll(".quick-search-item").forEach(button => {
-            button.addEventListener("click", () => {
-                document.getElementById("reg-search").value = button.dataset.search;
-                document.getElementById("reg-filter").value = button.dataset.type;
-                document.getElementById("registry-filter-form").submit();
+        function renderQuickItems(results, total) {
+            quickSearchList.replaceChildren();
+            results.forEach(item => {
+                const button = document.createElement("button");
+                button.type = "button";
+                button.className = "quick-search-item";
+                button.dataset.search = item.name;
+                button.dataset.type = item.type;
+                button.dataset.definition = item.id;
+                const badge = document.createElement("span");
+                badge.className = `type-tag type-tag--${item.type.toLowerCase()}`;
+                badge.textContent = item.type;
+                button.append(badge, document.createTextNode(item.name));
+                quickSearchList.appendChild(button);
             });
+            quickSearchStatus.textContent = total > results.length
+                ? `Showing ${results.length} of ${total} matching components.`
+                : `${total} matching component${total === 1 ? "" : "s"}.`;
+            bindQuickItems();
+        }
+
+        async function loadQuickItems() {
+            if (quickSearchController) quickSearchController.abort();
+            quickSearchController = new AbortController();
+            const query = quickSearchInput.value.trim();
+            const params = new URLSearchParams({q: query, limit: "30"});
+            try {
+                const response = await fetch(`{% url 'dev_catalog_search' %}?${params}`, {
+                    headers: {"X-Requested-With": "XMLHttpRequest"},
+                    signal: quickSearchController.signal,
+                });
+                if (!response.ok) throw new Error("Catalog search failed");
+                const data = await response.json();
+                renderQuickItems(data.results, data.total);
+            } catch (error) {
+                if (error.name !== "AbortError") {
+                    quickSearchStatus.textContent = "Could not load components.";
+                }
+            }
+        }
+
+        bindQuickItems();
+        quickSearchStatus.textContent = "Showing the first 30 components. Type to search all definitions.";
+        quickSearchInput.addEventListener("input", () => {
+            window.clearTimeout(quickSearchTimer);
+            quickSearchTimer = window.setTimeout(loadQuickItems, 200);
+        });
+        document.getElementById("reg-search").addEventListener("input", () => {
+            definitionFilter.value = "";
         });
-        quickSearchInput.addEventListener("input", runQuickSearch);
         document.querySelector(".quick-search").addEventListener("toggle", event => {
             if (event.target.open) quickSearchInput.focus();
         });
-        runQuickSearch();
-
-        if (document.getElementById("registry-table")) {
-            document.getElementById("reg-search").addEventListener("input", runFilters);
-            document.getElementById("reg-filter").addEventListener("change", runFilters);
-            document.getElementById("reg-site-filter").addEventListener("change", runFilters);
-        }
     </script>
 {% endblock %}

wagtail_developer_reference-0.1.4/wagtail_developer_reference/tests/test_auditor.py

@@ -0,0 +1,100 @@
+from django.test import SimpleTestCase, TestCase
+from wagtail.blocks import CharBlock, StreamBlock, StructBlock
+from wagtail.models import Page, Site
+
+from wagtail_developer_reference.wagtail_hooks import WagtailAuditor
+
+
+class TimelineBlock(StructBlock):
+    title = CharBlock(required=False)
+    content = StreamBlock(
+        [
+            ("logo", CharBlock(required=False)),
+            ("image", CharBlock(required=False)),
+        ],
+        required=False,
+    )
+
+
+class DefinitionPathTests(SimpleTestCase):
+    def setUp(self):
+        self.auditor = object.__new__(WagtailAuditor)
+        self.root_block = StreamBlock([("timeline", TimelineBlock())])
+
+    def test_raw_nested_stream_paths_are_exact_and_unique(self):
+        value = [
+            {
+                "type": "timeline",
+                "value": {
+                    "title": "First",
+                    "content": [
+                        {"type": "logo", "value": "A"},
+                        {"type": "image", "value": "B"},
+                        {"type": "image", "value": "C"},
+                    ],
+                },
+            }
+        ]
+        present = set()
+
+        self.auditor._collect_present_paths(self.root_block, value, (), present)
+
+        self.assertIn(("timeline",), present)
+        self.assertIn(("timeline", "title"), present)
+        self.assertIn(("timeline", "content", "logo"), present)
+        self.assertIn(("timeline", "content", "image"), present)
+        self.assertEqual(
+            len([path for path in present if path[-1] == "image"]), 1
+        )
+
+    def test_definition_id_includes_model_field_and_path(self):
+        first = WagtailAuditor._definition_id(
+            "BLOCK", "demo.articlepage", "body", ("timeline", "title")
+        )
+        same = WagtailAuditor._definition_id(
+            "BLOCK", "demo.articlepage", "body", ("timeline", "title")
+        )
+        other = WagtailAuditor._definition_id(
+            "BLOCK", "demo.homepage", "body", ("timeline", "title")
+        )
+
+        self.assertEqual(first, same)
+        self.assertNotEqual(first, other)
+
+
+class SiteScopeTests(TestCase):
+    def test_site_root_is_included_and_nested_site_is_excluded(self):
+        tree_root = Page.get_first_root_node()
+        site_root = tree_root.add_child(
+            instance=Page(title="Package test site", slug="package-test-site")
+        )
+        included_child = site_root.add_child(
+            instance=Page(title="Included", slug="included")
+        )
+        nested_root = site_root.add_child(
+            instance=Page(title="Nested site", slug="nested-site")
+        )
+        nested_child = nested_root.add_child(
+            instance=Page(title="Nested child", slug="nested-child")
+        )
+        site = Site.objects.create(
+            hostname="package-test.example",
+            port=8123,
+            root_page=site_root,
+        )
+        Site.objects.create(
+            hostname="nested-package-test.example",
+            port=8124,
+            root_page=nested_root,
+        )
+
+        page_ids = set(
+            WagtailAuditor()._scope_page_queryset(site).values_list(
+                "pk", flat=True
+            )
+        )
+
+        self.assertIn(site_root.pk, page_ids)
+        self.assertIn(included_child.pk, page_ids)
+        self.assertNotIn(nested_root.pk, page_ids)
+        self.assertNotIn(nested_child.pk, page_ids)