PyPI - wagtail-developer-reference - Versions diffs - 0.1.2__tar.gz → 0.1.3__tar.gz - Mend

wagtail-developer-reference 0.1.2tar.gz → 0.1.3tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (20) hide show

{wagtail_developer_reference-0.1.2/wagtail_developer_reference.egg-info → wagtail_developer_reference-0.1.3}/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wagtail-developer-reference
-Version: 0.1.2
+Version: 0.1.3
 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,15 +32,16 @@ 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
-* **Usage Tracking:** See exactly how many times a Page type or StreamField block is used across the site.
-* **Template Discovery:** Instantly see the file path for the template associated with every component.
-* **Interactive Audit:** Filter by type or search for specific field names to find where logic is implemented.
-* **Zero-Config:** No extra database tables or complex settings. It inspects your models and content on the fly.
+* **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.
+* **Template discovery:** See the template path associated with every component.
 ## Installation
-Compatibility: Python 3.9+ and Wagtail 4.1 through 7.4 LTS. Wagtail 7.4
-itself requires Python 3.10+.
+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+.
 1. Add \`wagtail_developer_reference\` to your \`INSTALLED_APPS\`:
    \`\`\`python

{wagtail_developer_reference-0.1.2 → wagtail_developer_reference-0.1.3}/README.md RENAMED Viewed

@@ -6,15 +6,16 @@
 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
-* **Usage Tracking:** See exactly how many times a Page type or StreamField block is used across the site.
-* **Template Discovery:** Instantly see the file path for the template associated with every component.
-* **Interactive Audit:** Filter by type or search for specific field names to find where logic is implemented.
-* **Zero-Config:** No extra database tables or complex settings. It inspects your models and content on the fly.
+* **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.
+* **Template discovery:** See the template path associated with every component.
 ## Installation
-Compatibility: Python 3.9+ and Wagtail 4.1 through 7.4 LTS. Wagtail 7.4
-itself requires Python 3.10+.
+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+.
 1. Add \`wagtail_developer_reference\` to your \`INSTALLED_APPS\`:
    \`\`\`python

{wagtail_developer_reference-0.1.2 → wagtail_developer_reference-0.1.3}/pyproject.toml RENAMED Viewed

@@ -1,6 +1,6 @@
 [project]
 name = "wagtail-developer-reference"
-version = "0.1.2"
+version = "0.1.3"
 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.2 → wagtail_developer_reference-0.1.3}/setup.py RENAMED Viewed

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

{wagtail_developer_reference-0.1.2 → wagtail_developer_reference-0.1.3}/wagtail_developer_reference/migrations/0001_initial.py RENAMED Viewed

@@ -1,7 +1,6 @@
 # Generated manually for wagtail-developer-reference.
-from django.db import migrations
-from django.db import models
+from django.db import migrations, models
 class Migration(migrations.Migration):

{wagtail_developer_reference-0.1.2 → wagtail_developer_reference-0.1.3}/wagtail_developer_reference/templates/detail.html RENAMED Viewed

@@ -98,6 +98,25 @@
     .empty-state p { font-size: 1.2rem; }
+    .registry-controls {
+        display: flex;
+        gap: 1rem;
+        margin-bottom: 1.5rem;
+        align-items: end;
+    }
+    .registry-controls {
+        background: #333; border-left: 0.3125rem solid #dcbd3d; padding: 1rem;
+    }
+    .registry-controls div:first-of-type { flex: 1; }
+    .registry-controls label { color: white; display: block; font-weight: bold; margin-bottom: 0.5rem; }
+    .registry-controls input {
+        background: #222; border: 0.0625rem solid #dcbd3d; box-sizing: border-box;
+        color: white; min-height: 2.5rem; padding: 0.6rem; width: 100%;
+    }
+    .usage-table-actions { display: flex; justify-content: flex-end; margin-top: 1rem; }
+    .copy-table-button { border-radius: 0; }
     [data-wagtail-theme="dark"] .listing tbody tr:hover {
         background-color: #333 !important;
     }
@@ -111,11 +130,21 @@
         <a href="{% url 'dev_reference' %}">&larr; Back to System Registry</a>
       </div>
       <h1>Locations for: <strong>{{ component_name }}</strong></h1>
-      <p>Found in {{ pages|length }} location{{ pages|length|pluralize }}</p>
+      <p>{{ page_obj.paginator.count }} location{{ page_obj.paginator.count|pluralize }} found</p>
     </div>
   </header>
   <div class="nice-padding">
+    <form method="get" class="registry-controls" role="search">
+      <input type="hidden" name="site" value="{{ site_filter }}">
+      <div>
+        <label for="usage-search">Search pages</label>
+        <input id="usage-search" type="search" name="q" value="{{ search_query }}" placeholder="Filter by page title or slug...">
+      </div>
+      <div>
+        <button type="submit" class="button">Search</button>
+      </div>
+    </form>
     <table class="listing" id="usage-table">
       <thead>
         <tr>
@@ -151,12 +180,38 @@
         {% endfor %}
       </tbody>
     </table>
+    <div class="usage-table-actions">
+      <button id="copy-usage-table" type="button" class="button button-secondary copy-table-button">Copy displayed table</button>
+    </div>
+    {% if page_obj.paginator.num_pages > 1 %}
+      <nav class="pagination" aria-label="Usage result pages">
+        {% if page_obj.has_previous %}
+          <a class="button" href="?site={{ site_filter|urlencode }}&amp;q={{ search_query|urlencode }}&amp;page={{ page_obj.previous_page_number }}">Previous</a>
+        {% endif %}
+        <span>Page {{ page_obj.number }} of {{ page_obj.paginator.num_pages }}</span>
+        {% if page_obj.has_next %}
+          <a class="button" href="?site={{ site_filter|urlencode }}&amp;q={{ search_query|urlencode }}&amp;page={{ page_obj.next_page_number }}">Next</a>
+        {% endif %}
+      </nav>
+    {% endif %}
   </div>
   <script>
     let currentSortCol = -1;
     let sortAsc = true;
+    function copyUsageTable() {
+        const headers = ["Page Title", "Status", "URL Path"];
+        const rows = Array.from(document.querySelectorAll("#usage-body .usage-row"));
+        const values = rows.map(row => [0, 1, 2].map(index => row.cells[index].innerText.trim().replace(/\s+/g, " ")));
+        const text = [headers, ...values].map(row => row.join("\t")).join("\n");
+        const button = document.getElementById("copy-usage-table");
+        navigator.clipboard.writeText(text).then(() => {
+            button.textContent = "Copied";
+            window.setTimeout(() => { button.textContent = "Copy displayed table"; }, 1500);
+        });
+    }
     function sortTable(colIdx) {
         const tbody = document.getElementById("usage-body");
         const rows = Array.from(tbody.querySelectorAll(".usage-row"));
@@ -173,12 +228,14 @@
             if (colIdx === 1) {
                 valA = parseInt(a.cells[colIdx].getAttribute('data-sort'));
                 valB = parseInt(b.cells[colIdx].getAttribute('data-sort'));
-                return sortAsc ? valA - valB : valB - valueA;
+                return sortAsc ? valA - valB : valB - valA;
             }
             valA = a.cells[colIdx].textContent.trim().toLowerCase();
             valB = b.cells[colIdx].textContent.trim().toLowerCase();
             return sortAsc ? valA.localeCompare(valB) : valB.localeCompare(valA);
         }).forEach(row => tbody.appendChild(row));
     }
+    document.getElementById("copy-usage-table").addEventListener("click", copyUsageTable);
   </script>
-{% endblock %}
+{% endblock %}

wagtail_developer_reference-0.1.3/wagtail_developer_reference/templates/index.html ADDED Viewed

@@ -0,0 +1,313 @@
+{% extends "wagtailadmin/base.html" %}
+{% block titletag %}System Registry{% endblock %}
+{% block extra_css %}
+<style>
+    .registry-controls {
+        display: flex; gap: 1rem; margin-bottom: 1.5rem;
+        background-color: #4a4a4a; padding: 1.25rem; border-left: 5px solid #dcbd3d;
+        align-items: end;
+    }
+    .registry-controls { flex-wrap: wrap; }
+    .registry-controls div { flex: 1 1 10rem; }
+    .registry-controls .registry-search { flex: 3 1 20rem; }
+    .registry-controls .usage-range { flex: 0 1 6rem; }
+    .registry-controls .filter-actions {
+        align-items: end; display: flex; flex: 0 0 auto; gap: 0.5rem;
+    }
+    .registry-controls .filter-actions .button { margin: 0; white-space: nowrap; }
+    .quick-search {
+        background: #333; border-left: 5px solid #dcbd3d; margin-bottom: 1rem;
+    }
+    .quick-search summary {
+        color: white; cursor: pointer; font-weight: bold; padding: 0.9rem 1.25rem;
+    }
+    .quick-search-filter {
+        box-sizing: border-box; margin: 0 1.25rem 0.75rem; max-width: 34rem;
+        min-height: 2.5rem; padding: 0.5rem; width: calc(100% - 2.5rem);
+    }
+    .quick-search-status { color: #ccc; display: block; font-size: 0.85rem; padding: 0 1.25rem 0.75rem; }
+    .quick-search-list {
+        display: flex; flex-wrap: wrap; gap: 0.5rem; padding: 0 1.25rem 1.25rem;
+    }
+    .quick-search-item {
+        background: #222; border: 1px solid #777; color: white; cursor: pointer;
+        font: inherit; padding: 0.35rem 0.5rem; text-align: left;
+    }
+    .quick-search-item:hover, .quick-search-item:focus {
+        border-color: #dcbd3d; color: #dcbd3d;
+    }
+    .quick-search-item .type-tag { margin-right: 0.35rem; }
+    .registry-controls label { display: block; font-weight: bold; color: white; margin-bottom: 0.5rem; }
+    .registry-controls input, .registry-controls select {
+        box-sizing: border-box; height: 2.5rem; width: 100%;
+        border: 1px solid #dcbd3d; background: #333; color: white; border-radius: 0;
+    }
+    .listing thead tr { border-bottom: 2px solid #dcbd3d; }
+    .listing tbody td { vertical-align: top; }
+    .col-centered { text-align: center; width: 5rem; }
+    .col-site { width: 10rem; }
+    .col-type { width: 8rem; white-space: nowrap; }
+    .sortable { cursor: pointer; position: relative; transition: background 0.2s; }
+    .sortable:hover { background: #444; }
+    .sortable::after {
+        content: '↕';
+        font-size: 0.8rem;
+        margin-left: 5px;
+        opacity: 0.3;
+    }
+    .type-tag {
+        background: #222; color: #dcbd3d; border: 1px solid #dcbd3d;
+        padding: 2px 10px; text-transform: uppercase; font-size: 0.7rem;
+        display: inline-block; white-space: nowrap;
+        cursor: default; pointer-events: none;
+    }
+    .type-tag--page { background: #153a5b; border-color: #5db6ff; color: #b9e2ff; }
+    .type-tag--block { background: #3c2459; border-color: #bf8cff; color: #e2c8ff; }
+    .field-pill {
+        background: #222; border: 1px solid #dcbd3d; padding: 2px 6px;
+        display: inline-block; font-size: 0.75rem; white-space: nowrap;
+    }
+    .field-pill--metadata { border-color: #777; background: #333; }
+    .field-type { color: #aaa; font-size: 0.8em; }
+    .field-toggle {
+        background: #222;
+        border: 1px solid #dcbd3d;
+        color: #dcbd3d;
+        cursor: pointer;
+        font-size: 0.75rem;
+        padding: 0.3rem 0.5rem;
+        text-align: left;
+    }
+    .field-toggle:hover { background: #333; }
+    .field-toggle::before { content: "▸"; margin-right: 0.4rem; }
+    .field-toggle[aria-expanded="true"]::before { content: "▾"; }
+    .field-cell { position: relative; }
+    .field-details {
+        align-items: flex-start; background: #222; border: 1px solid #dcbd3d;
+        box-shadow: 0 0.5rem 1rem rgba(0, 0, 0, 0.35); display: flex;
+        flex-wrap: wrap; gap: 0.25rem; left: 0; margin-top: 0.5rem;
+        max-width: 36rem; min-width: 20rem; padding: 0.5rem; position: absolute;
+        top: 100%; z-index: 10;
+    }
+    .field-details[hidden] { display: none; }
+    .count-draft { color: #dcbd3d; font-weight: bold; }
+    .count-live { color: #1fb53a; font-weight: bold; }
+    .zero-usage { color: #af7f7f; opacity: 0.5; }
+    .usage-link { background: #dcbd3d !important; color: #222 !important; font-weight: bold; border-radius: 0; }
+    .template-label { color: #ccc; font-family: monospace; font-size: 0.7rem; }
+    .template-copy { margin-left: 0.35rem; padding: 0.15rem 0.35rem; }
+    .template-empty { color: #aaa; }
+    [data-wagtail-theme="dark"] .listing tbody tr:hover {
+        background-color: #333 !important;
+    }
+</style>
+{% endblock %}
+{% block content %}
+    {% include "wagtailadmin/shared/header.html" with title="System Registry" icon="code" %}
+    <div class="nice-padding">
+        <details class="quick-search">
+            <summary>Browse pages and blocks</summary>
+            <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 }}
+                    </button>
+                {% endfor %}
+            </div>
+        </details>
+        <form id="registry-filter-form" method="get" class="registry-controls">
+            <input type="hidden" name="apply" value="1">
+            <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>
+            <div class="usage-range"><label for="min-usage">Min usage</label><input id="min-usage" type="number" min="0" name="min_usage" value="{{ filters.min_usage }}"></div>
+            <div class="usage-range"><label for="max-usage">Max usage</label><input id="max-usage" type="number" min="0" name="max_usage" value="{{ filters.max_usage }}"></div>
+            <div class="filter-actions"><button type="submit" class="button">Apply Filters</button><a class="button button-secondary" href="{% url 'dev_reference' %}">Clear</a></div>
+        </form>
+        {% if filter_error %}<p class="error-message">{{ filter_error }}</p>{% endif %}
+        {% if is_applied %}
+        <table class="listing" id="registry-table">
+            <thead>
+                <tr>
+                    <th class="sortable col-site" onclick="sortTable(0)">Site</th>
+                    <th class="sortable" onclick="sortTable(1)">Hierarchy</th>
+                    <th class="sortable col-type" onclick="sortTable(2)">Type</th>
+                    <th class="sortable" onclick="sortTable(3)">Structure & Metadata</th>
+                    <th class="sortable col-centered" onclick="sortTable(4)">Draft</th>
+                    <th class="sortable col-centered" onclick="sortTable(5)">Live</th>
+                    <th class="sortable col-centered" onclick="sortTable(6)">Total</th>
+                    <th class="sortable" onclick="sortTable(7)">Template Path</th>
+                </tr>
+            </thead>
+            <tbody id="registry-body">
+                {% for item in audit_data %}
+                <tr class="registry-row" data-type="{{ item.type|upper }}" data-site="{{ item.site_id }}">
+                    <td class="col-site">{{ item.site_name }}</td>
+                    <td><strong>{{ item.hierarchy }}</strong></td>
+                    <td class="col-type"><span class="type-tag type-tag--{{ item.type|lower }}">{{ item.type }}</span></td>
+                    <td class="field-cell">
+                        <button
+                            type="button"
+                            class="field-toggle"
+                            aria-expanded="false"
+                            aria-controls="field-details-{{ forloop.counter }}"
+                        >
+                            S: {{ item.fields.structure|length }} · M: {{ item.fields.metadata|length }}
+                        </button>
+                        <div id="field-details-{{ forloop.counter }}" class="field-details" hidden>
+                            {% for field_info in item.fields.structure %}
+                                <div class="field-pill">
+                                    <code>{{ field_info.label }} <small class="field-type">({{ field_info.type }})</small></code>
+                                </div>
+                            {% endfor %}
+                            {% for field_info in item.fields.metadata %}
+                                <div class="field-pill field-pill--metadata">
+                                    <code>{{ field_info.label }} <small class="field-type">({{ field_info.type }})</small></code>
+                                </div>
+                            {% 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>
+                    <td>
+                        {% if item.template %}
+                            <span class="template-label" title="{{ item.template }}">{{ item.template_label }}</span>
+                            <button type="button" class="template-copy" data-template="{{ item.template }}">Copy</button>
+                        {% else %}
+                            <span class="template-empty">—</span>
+                        {% endif %}
+                    </td>
+                </tr>
+                {% endfor %}
+            </tbody>
+        </table>
+        {% else %}
+            <p class="help-block">Choose filters and select <strong>Apply Filters</strong> to load registry usage.</p>
+        {% endif %}
+    </div>
+    <script>
+        let currentSortColumn = -1;
+        let isSortAscending = true;
+        function sortTable(columnIndex) {
+            const tableBody = document.getElementById("registry-body");
+            const tableRows = Array.from(tableBody.querySelectorAll(".registry-row"));
+            isSortAscending = (currentSortColumn === columnIndex) ? !isSortAscending : true;
+            currentSortColumn = columnIndex;
+            tableRows.sort((rowA, rowB) => {
+                let cellA = rowA.cells[columnIndex];
+                let cellB = rowB.cells[columnIndex];
+                let valueA = cellA.getAttribute('data-sort') || cellA.textContent.trim().toLowerCase();
+                let valueB = cellB.getAttribute('data-sort') || cellB.textContent.trim().toLowerCase();
+                if (!isNaN(parseFloat(valueA)) && isFinite(valueA) && !isNaN(parseFloat(valueB)) && isFinite(valueB)) {
+                    return isSortAscending ? valueA - valueB : valueB - valueA;
+                }
+                return isSortAscending ? valueA.localeCompare(valueB) : valueB.localeCompare(valueA);
+            }).forEach(sortedRow => tableBody.appendChild(sortedRow));
+        }
+        function runFilters() {
+            const searchTerm = document.getElementById("reg-search").value.toLowerCase();
+            const typeFilter = document.getElementById("reg-filter").value;
+            const siteFilter = document.getElementById("reg-site-filter").value;
+            document.querySelectorAll(".registry-row").forEach(row => {
+                const textMatches = row.textContent.toLowerCase().includes(searchTerm);
+                const typeMatches = typeFilter === "ALL" || row.dataset.type === typeFilter;
+                const siteMatches = siteFilter === "ALL" || row.dataset.site === siteFilter;
+                row.style.display = textMatches && typeMatches && siteMatches ? "" : "none";
+            });
+        }
+        document.querySelectorAll(".field-toggle").forEach(button => {
+            button.addEventListener("click", () => {
+                const details = document.getElementById(button.getAttribute("aria-controls"));
+                const isExpanded = button.getAttribute("aria-expanded") === "true";
+                document.querySelectorAll(".field-toggle").forEach(otherButton => {
+                    otherButton.setAttribute("aria-expanded", "false");
+                    document.getElementById(otherButton.getAttribute("aria-controls")).hidden = true;
+                });
+                if (!isExpanded) {
+                    button.setAttribute("aria-expanded", "true");
+                    details.hidden = false;
+                }
+            });
+        });
+        document.querySelectorAll(".template-copy").forEach(button => {
+            button.addEventListener("click", () => {
+                navigator.clipboard.writeText(button.dataset.template).then(() => {
+                    button.textContent = "Copied";
+                    window.setTimeout(() => { button.textContent = "Copy"; }, 1500);
+                });
+            });
+        });
+        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;
+        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;
+            });
+            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();
+            });
+        });
+        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.2 → wagtail_developer_reference-0.1.3}/wagtail_developer_reference/wagtail_hooks.py RENAMED Viewed

@@ -1,25 +1,24 @@
+# ruff: noqa: E501
 from __future__ import annotations
 import inspect
 from collections.abc import Iterable
-from typing import Any, Literal, TypedDict
+from pathlib import Path
+from typing import Any, Literal, NotRequired, TypedDict
 from django.contrib.auth.decorators import user_passes_test
 from django.core.exceptions import PermissionDenied
-from django.db.models import Field
+from django.core.paginator import Paginator
+from django.db.models import Field, Q
 from django.http import HttpRequest, HttpResponse
 from django.shortcuts import render
 from django.template.loader import get_template
-from django.urls import path
-from django.urls import reverse
+from django.urls import path, reverse
 from django.urls.resolvers import URLPattern
 from wagtail import hooks
 from wagtail.admin.menu import MenuItem
-from wagtail.blocks import StructBlock
 from wagtail.fields import StreamField
-from wagtail.models import Page
-from wagtail.models import Site, get_page_models
+from wagtail.models import Page, Site, get_page_models
 ACCESS_PERMISSION_APP_LABEL: str = "wagtail_developer_reference"
 ACCESS_PERMISSION_CODENAME: str = "access_developer_reference"
@@ -34,19 +33,27 @@ class UsageData(TypedDict):
     draft: int
+class FieldInfo(TypedDict):
+    label: str
+    type: str
+    block_name: NotRequired[str | None]
 class FieldGroups(TypedDict):
-    structure: list[str]
-    metadata: list[str]
+    structure: list[FieldInfo]
+    metadata: list[FieldInfo]
 class AuditItem(TypedDict):
+    site_id: int
     site_name: str
     hierarchy: str
     clean_name: str
     type: ComponentType
     fields: FieldGroups
     usage: UsageData
-    template: str
+    template: str | None
+    template_label: str | None
 def user_can_access_developer_reference(user: Any) -> bool:
@@ -99,38 +106,35 @@ class WagtailAuditor:
             "latest_revision_created_at",
         }
-    def get_template_path(self, template_name: str | None) -> str:
+    def get_template_path(self, template_name: str | None) -> str | None:
         if not template_name:
-            return "Default Rendering"
+            return None
         try:
             return get_template(template_name).origin.name
         except Exception:
-            return "Template not found"
+            return template_name
-    def _analyze_model_field(
-        self,
-        field: Field[Any, Any],
-    ) -> tuple[str | None, FieldCategory | None]:
-        if field.name in self.excluded_fields:
+    def get_template_label(self, template_path: str | None) -> str | None:
+        return Path(template_path).name if template_path else None
+    def _analyze_model_field(self, field: Field[Any, Any]) -> tuple[FieldInfo | None, FieldCategory | None]:
+        if field.name in self.excluded_fields or (field.is_relation and not field.many_to_one):
             return None, None
-        if not field.is_relation or field.many_to_one:
-            label = getattr(field, "verbose_name", field.name)
-            if hasattr(label, "__str__"):
-                label = str(label).capitalize()
-            field_type = type(field).__name__
-            is_structure = "StreamField" in field_type or "RichTextField" in field_type
-            category = "structure" if is_structure else "metadata"
-            return f"{label} ({field_type})", category
-        return None, None
+        field_type = type(field).__name__
+        category: FieldCategory = "structure" if isinstance(field, StreamField) or "RichTextField" in field_type else "metadata"
+        return {"label": str(getattr(field, "verbose_name", field.name)).capitalize(), "type": field_type}, category
     def get_internal_structure(self, object_instance: Any) -> FieldGroups:
-        structure_fields: list[str] = []
-        metadata_fields: list[str] = []
+        structure_fields: list[FieldInfo] = []
+        metadata_fields: list[FieldInfo] = []
         if hasattr(object_instance, "child_blocks"):
             for name, block in object_instance.child_blocks.items():
-                label = getattr(block.meta, "label", name)
-                structure_fields.append(f"{label} ({type(block).__name__})")
+                label = getattr(block.meta, "label", None) or name
+                structure_fields.append(
+                    {"label": str(label), "type": type(block).__name__}
+                )
         elif hasattr(object_instance, "_meta"):
             for field in object_instance._meta.get_fields():
                 info, category = self._analyze_model_field(field)
@@ -172,64 +176,44 @@ class WagtailAuditor:
             "draft": total_count - live_count,
         }
-    def process_block(
-        self,
-        block_name: str,
-        block_object: Any,
-        parent_label: str,
-        site: Site,
-    ) -> None:
+    def process_block(self, block_name: str, block_object: Any, parent_label: str, site: Site, include_usage: bool = False) -> None:
         is_class = inspect.isclass(block_object)
-        block_class = (
-            block_object.__name__ if is_class else block_object.__class__.__name__
-        )
-        signature = f"{site.id}_{block_class}_{block_name}"
+        block_class = block_object.__name__ if is_class else block_object.__class__.__name__
+        signature = f"{site.id}_{parent_label}_{block_class}_{block_name}"
         if signature in self.seen_blocks:
             return
-        site_usage = {"live": 0, "total": 0, "draft": 0}
-        for model in self.models_with_streamfields:
-            usage_data = self._get_usage_for_site(model, site, block_name)
-            site_usage["live"] += usage_data["live"]
-            site_usage["total"] += usage_data["total"]
-            site_usage["draft"] += usage_data["draft"]
-        block_label = str(getattr(block_object.meta, "label", block_name))
-        self.results.append(
-            {
-                "site_name": str(site),
-                "hierarchy": f"{parent_label} → {block_label}",
-                "clean_name": block_name,
-                "type": "BLOCK",
-                "fields": self.get_internal_structure(block_object),
-                "usage": site_usage,
-                "template": self.get_template_path(
-                    getattr(block_object.meta, "template", None)
-                ),
-            }
-        )
+        block_label = str(getattr(block_object.meta, "label", None) or block_name)
+        template_path = self.get_template_path(getattr(block_object.meta, "template", None))
+        usage = {"live": 0, "total": 0, "draft": 0}
+        if include_usage:
+            for model in self.models_with_streamfields:
+                model_usage = self._get_usage_for_site(model, site, block_name)
+                for key in usage:
+                    usage[key] += model_usage[key]
+        self.results.append({"site_id": site.id, "site_name": site.site_name, "hierarchy": f"{parent_label} → {block_label}", "clean_name": block_name, "type": "BLOCK", "fields": self.get_internal_structure(block_object), "usage": usage, "template": template_path, "template_label": self.get_template_label(template_path)})
         self.seen_blocks.add(signature)
+        for child_name, child_object in getattr(block_object, "child_blocks", {}).items():
+            self.process_block(child_name, child_object, f"{parent_label} → {block_label}", site, include_usage)
-        if isinstance(block_object, StructBlock):
-            for child_name, child_object in block_object.child_blocks.items():
-                self.process_block(child_name, child_object, parent_label, site)
-    def run(self) -> list[AuditItem]:
+    def run(self, include_usage: bool = False) -> list[AuditItem]:
         for site in self.sites:
             for model in self.all_page_models:
-                usage_data = self._get_usage_for_site(model, site)
+                usage_data = self._get_usage_for_site(model, site) if include_usage else {"live": 0, "total": 0, "draft": 0}
                 default_tpl = f"{model._meta.app_label}/{model._meta.model_name}.html"
+                template_path = self.get_template_path(
+                    getattr(model, "template", default_tpl)
+                )
                 self.results.append(
                     {
-                        "site_name": str(site),
+                        "site_id": site.id,
+                        "site_name": site.site_name,
                         "hierarchy": str(model._meta.verbose_name).title(),
                         "clean_name": model.__name__,
                         "type": "PAGE",
                         "fields": self.get_internal_structure(model),
                         "usage": usage_data,
-                        "template": self.get_template_path(
-                            getattr(model, "template", default_tpl)
-                        ),
+                        "template": template_path,
+                        "template_label": self.get_template_label(template_path),
                     }
                 )
                 for field in model._meta.get_fields():
@@ -241,19 +225,45 @@ class WagtailAuditor:
                                 block_object,
                                 str(model._meta.verbose_name).title(),
                                 site,
+                                include_usage,
                             )
         return self.results
 @user_passes_test(require_developer_reference_access)
 def developer_reference_view(request: HttpRequest) -> HttpResponse:
+    applied = request.GET.get("apply") == "1"
     auditor = WagtailAuditor()
-    audit_results = auditor.run()
-    sorted_results = sorted(
-        audit_results,
-        key=lambda item: (item["site_name"], item["hierarchy"]),
-    )
-    return render(request, "index.html", {"audit_data": sorted_results})
+    audit_results = auditor.run(include_usage=applied)
+    quick_search_by_component = {}
+    for item in audit_results:
+        key = (item["type"], item["hierarchy"])
+        quick_search_by_component.setdefault(key, (item["type"], item["hierarchy"], item["hierarchy"]))
+    quick_search_items = sorted(quick_search_by_component.values(), key=lambda item: (item[2].casefold(), item[0]))
+    filters = {"q": request.GET.get("q", "").strip(), "type": request.GET.get("type", "ALL"), "site": request.GET.get("site", ""), "min_usage": request.GET.get("min_usage", ""), "max_usage": request.GET.get("max_usage", "")}
+    error = ""
+    filtered_results: list[AuditItem] = []
+    if applied:
+        try:
+            minimum = int(filters["min_usage"]) if filters["min_usage"] else None
+            maximum = int(filters["max_usage"]) if filters["max_usage"] else None
+            if (minimum is not None and minimum < 0) or (maximum is not None and maximum < 0) or (minimum is not None and maximum is not None and minimum > maximum):
+                raise ValueError
+        except ValueError:
+            error = "Usage range must contain non-negative numbers, with min no greater than max."
+            minimum = maximum = None
+        if not error:
+            query = filters["q"].casefold()
+            for item in audit_results:
+                matches_query = not query or query in " ".join((item["site_name"], item["hierarchy"], item["clean_name"])).casefold()
+                matches_type = filters["type"] == "ALL" or item["type"] == filters["type"]
+                matches_site = not filters["site"] or str(item["site_id"]) == filters["site"]
+                total = item["usage"]["total"]
+                matches_min = minimum is None or total >= minimum
+                matches_max = maximum is None or total <= maximum
+                if matches_query and matches_type and matches_site and matches_min and matches_max:
+                    filtered_results.append(item)
+    return render(request, "index.html", {"audit_data": sorted(filtered_results, key=lambda item: (item["site_name"], item["hierarchy"])), "quick_search_items": quick_search_items, "sites": Site.objects.order_by("site_name", "id"), "filters": filters, "is_applied": applied, "filter_error": error})
 @user_passes_test(require_developer_reference_access)
@@ -262,17 +272,28 @@ def developer_usage_detail_view(
     component_type: str,
     component_name: str,
 ) -> HttpResponse:
-    site_filter_name = request.GET.get("site")
-    found_pages: list[Page] = []
+    site_filter = request.GET.get("site")
+    site = Site.objects.filter(pk=site_filter).first()
+    pages = Page.objects.none()
+    # Do not load every matching page into Python. Scope the query to the site
+    # and let the database return only the current results page.
+    if site_filter:
+        site_pages = (
+            Page.objects.descendant_of(site.root_page) if site else Page.objects.none()
+        )
+    else:
+        site_pages = Page.objects.all()
     if component_type == "PAGE":
         target_model = next(
             (model for model in get_page_models() if model.__name__ == component_name),
             None,
         )
         if target_model:
-            found_pages = list(target_model.objects.all())
+            pages = site_pages.filter(pk__in=target_model.objects.values("pk"))
     else:
         search_key = f'"{component_name}"'
+        component_filter = Q()
         for model in get_page_models():
             stream_fields = [
                 f.name
@@ -280,28 +301,31 @@ def developer_usage_detail_view(
                 if isinstance(f, StreamField)
             ]
             for field_name in stream_fields:
-                found_pages.extend(
-                    list(
-                        model.objects.filter(
-                            **{f"{field_name}__icontains": search_key}
-                        )
-                    )
+                component_filter |= Q(
+                    pk__in=model.objects.filter(
+                        **{f"{field_name}__icontains": search_key}
+                    ).values("pk")
                 )
+        if component_filter:
+            pages = site_pages.filter(component_filter)
-    if site_filter_name:
-        found_pages = [
-            page
-            for page in found_pages
-            if str(page.get_site()) == site_filter_name
-        ]
+    search_query = request.GET.get("q", "").strip()
+    if search_query:
+        pages = pages.filter(
+            Q(title__icontains=search_query) | Q(slug__icontains=search_query)
+        )
-    unique_pages = {page.id: page for page in found_pages}.values()
+    paginator = Paginator(pages.order_by("title", "pk").distinct(), 50)
+    page_obj = paginator.get_page(request.GET.get("page"))
     return render(
         request,
         "detail.html",
         {
             "component_name": component_name,
-            "pages": unique_pages,
+            "pages": page_obj,
+            "page_obj": page_obj,
+            "search_query": search_query,
+            "site_filter": site_filter or "",
         },
     )

{wagtail_developer_reference-0.1.2 → wagtail_developer_reference-0.1.3/wagtail_developer_reference.egg-info}/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wagtail-developer-reference
-Version: 0.1.2
+Version: 0.1.3
 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,15 +32,16 @@ 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
-* **Usage Tracking:** See exactly how many times a Page type or StreamField block is used across the site.
-* **Template Discovery:** Instantly see the file path for the template associated with every component.
-* **Interactive Audit:** Filter by type or search for specific field names to find where logic is implemented.
-* **Zero-Config:** No extra database tables or complex settings. It inspects your models and content on the fly.
+* **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.
+* **Template discovery:** See the template path associated with every component.
 ## Installation
-Compatibility: Python 3.9+ and Wagtail 4.1 through 7.4 LTS. Wagtail 7.4
-itself requires Python 3.10+.
+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+.
 1. Add \`wagtail_developer_reference\` to your \`INSTALLED_APPS\`:
    \`\`\`python

wagtail_developer_reference-0.1.2/wagtail_developer_reference/templates/index.html DELETED Viewed

@@ -1,164 +0,0 @@
-{% extends "wagtailadmin/base.html" %}
-{% block titletag %}System Registry{% endblock %}
-{% block extra_css %}
-<style>
-    .registry-controls {
-        display: flex; gap: 1rem; margin-bottom: 1.5rem;
-        background-color: #4a4a4a; padding: 1.25rem; border-left: 5px solid #dcbd3d;
-    }
-    .registry-controls div { flex: 1; }
-    .registry-controls label { display: block; font-weight: bold; color: white; margin-bottom: 0.5rem; }
-    .registry-controls input, .registry-controls select {
-        width: 100%; padding: 0.6rem; border: 1px solid #dcbd3d; background: #333; color: white; border-radius: 0;
-    }
-    .listing thead tr { border-bottom: 2px solid #dcbd3d; }
-    .col-centered { text-align: center; width: 5rem; }
-    .col-site { width: 10rem; }
-    .col-type { width: 8rem; white-space: nowrap; }
-    .sortable { cursor: pointer; position: relative; transition: background 0.2s; }
-    .sortable:hover { background: #444; }
-    .sortable::after {
-        content: '↕';
-        font-size: 0.8rem;
-        margin-left: 5px;
-        opacity: 0.3;
-    }
-    .type-tag {
-        background: #222; color: #dcbd3d; border: 1px solid #dcbd3d;
-        padding: 2px 10px; text-transform: uppercase; font-size: 0.7rem;
-        display: inline-block; white-space: nowrap;
-    }
-    .field-pill {
-        background: #222; border: 1px solid #dcbd3d; padding: 2px 6px;
-        margin-bottom: 4px; display: inline-block; font-size: 0.75rem;
-    }
-    .field-pill--metadata { border-color: #777; background: #333; }
-    .count-draft { color: #dcbd3d; font-weight: bold; }
-    .count-live { color: #1fb53a; font-weight: bold; }
-    .zero-usage { color: #af7f7f; opacity: 0.5; }
-    .usage-link { background: #dcbd3d !important; color: #222 !important; font-weight: bold; border-radius: 0; }
-    .template-path { color: #ccc; font-family: monospace; font-size: 0.7rem; cursor: pointer; }
-    [data-wagtail-theme="dark"] .listing tbody tr:hover {
-        background-color: #333 !important;
-    }
-</style>
-{% endblock %}
-{% block content %}
-    {% include "wagtailadmin/shared/header.html" with title="System Registry" icon="code" %}
-    <div class="nice-padding">
-        <div class="registry-controls">
-            <div>
-                <label>Search Registry</label>
-                <input type="text" id="reg-search" placeholder="Filter by name, field or site...">
-            </div>
-            <div id="type-filter-container">
-                <label>Component Type</label>
-                <select id="reg-filter">
-                    <option value="ALL">All</option>
-                    <option value="PAGE">Pages Only</option>
-                    <option value="BLOCK">Blocks Only</option>
-                </select>
-            </div>
-        </div>
-        <table class="listing" id="registry-table">
-            <thead>
-                <tr>
-                    <th class="sortable col-site" onclick="sortTable(0)">Site</th>
-                    <th class="sortable" onclick="sortTable(1)">Hierarchy</th>
-                    <th class="sortable col-type" onclick="sortTable(2)">Type</th>
-                    <th class="sortable" onclick="sortTable(3)">Structure & Metadata</th>
-                    <th class="sortable col-centered" onclick="sortTable(4)">Draft</th>
-                    <th class="sortable col-centered" onclick="sortTable(5)">Live</th>
-                    <th class="sortable col-centered" onclick="sortTable(6)">Total</th>
-                    <th class="sortable" onclick="sortTable(7)">Template Path</th>
-                </tr>
-            </thead>
-            <tbody id="registry-body">
-                {% for item in audit_data %}
-                <tr class="registry-row" data-type="{{ item.type|upper }}">
-                    <td class="col-site">{{ item.site_name }}</td>
-                    <td><strong>{{ item.hierarchy }}</strong></td>
-                    <td class="col-type"><span class="type-tag">{{ item.type }}</span></td>
-                    <td>
-                        {% for field_info in item.fields.structure %}
-                            <div class="field-pill"><code>{{ field_info }}</code></div>
-                        {% endfor %}
-                        {% for field_info in item.fields.metadata %}
-                            <div class="field-pill field-pill--metadata"><code>{{ field_info }}</code></div>
-                        {% endfor %}
-                    </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_name }}" class="button button-small usage-link">
-                                {{ item.usage.total }}
-                            </a>
-                        {% else %}
-                            <span class="zero-usage">0</span>
-                        {% endif %}
-                    </td>
-                    <td>
-                        <small class="template-path" onclick="navigator.clipboard.writeText(this.textContent.trim())">
-                            {{ item.template }}
-                        </small>
-                    </td>
-                </tr>
-                {% endfor %}
-            </tbody>
-        </table>
-    </div>
-    <script>
-        let currentSortColumn = -1;
-        let isSortAscending = true;
-        function sortTable(columnIndex) {
-            const tableBody = document.getElementById("registry-body");
-            const tableRows = Array.from(tableBody.querySelectorAll(".registry-row"));
-            isSortAscending = (currentSortColumn === columnIndex) ? !isSortAscending : true;
-            currentSortColumn = columnIndex;
-            tableRows.sort((rowA, rowB) => {
-                let cellA = rowA.cells[columnIndex];
-                let cellB = rowB.cells[columnIndex];
-                let valueA = cellA.getAttribute('data-sort') || cellA.textContent.trim().toLowerCase();
-                let valueB = cellB.getAttribute('data-sort') || cellB.textContent.trim().toLowerCase();
-                if (!isNaN(parseFloat(valueA)) && isFinite(valueA) && !isNaN(parseFloat(valueB)) && isFinite(valueB)) {
-                    return isSortAscending ? valueA - valueB : valueB - valueA;
-                }
-                return isSortAscending ? valueA.localeCompare(valueB) : valueB.localeCompare(valueA);
-            }).forEach(sortedRow => tableBody.appendChild(sortedRow));
-        }
-        function runFilters() {
-            const searchTerm = document.getElementById('reg-search').value.toLowerCase();
-            const filterValue = document.getElementById('reg-filter').value;
-            document.querySelectorAll('.registry-row').forEach(row => {
-                const textMatches = row.textContent.toLowerCase().includes(searchTerm);
-                const rowType = row.getAttribute('data-type');
-                const typeMatches = (filterValue === 'ALL') || (rowType === filterValue);
-                row.style.display = (textMatches && typeMatches) ? '' : 'none';
-            });
-        }
-        document.getElementById('reg-search').addEventListener('input', runFilters);
-        document.getElementById('reg-filter').addEventListener('change', runFilters);
-    </script>
-{% endblock %}