django-newadmin 0.1.0a1__py3-none-any.whl

django_newadmin-0.1.0a1.dist-info/METADATA

@@ -0,0 +1,139 @@
+Metadata-Version: 2.5
+Name: django-newadmin
+Version: 0.1.0a1
+Summary: A polished, extensible theme for Django's built-in admin.
+Project-URL: Documentation, https://carocha.github.io/django-newadmin/
+Project-URL: Repository, https://github.com/CARocha/django-newadmin
+Project-URL: Issues, https://github.com/CARocha/django-newadmin/issues
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 6.0
+Classifier: Framework :: Django :: 6.1
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Topic :: Software Development :: User Interfaces
+Requires-Python: >=3.13
+Requires-Dist: django<6.2,>=6.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: playwright>=1.52; extra == 'dev'
+Requires-Dist: pytest-django>=4.11; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Requires-Dist: ruff>=0.11; extra == 'dev'
+Requires-Dist: twine<8,>=7; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: furo<2027,>=2025.7.19; extra == 'docs'
+Requires-Dist: myst-parser<6,>=4; extra == 'docs'
+Requires-Dist: sphinx<10,>=8.2; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# django-newadmin
+
+A modern, extensible light-and-dark theme for Django's built-in admin.
+
+**Status:** 0.1.0a1 alpha candidate. Django 6.0 and 6.1 on Python 3.13 and 3.14
+are tested locally; GitHub Actions repeats this matrix after the code is pushed.
+TestPyPI publication is manual; PyPI publication runs only when a GitHub Release
+uses the matching version tag. License: BSD-3-Clause.
+
+**Documentation:** [CARocha.github.io/django-newadmin](https://carocha.github.io/django-newadmin/)
+will be published by GitHub Actions after Pages is enabled for this repository.
+
+## Development setup
+
+```sh
+python3.14 -m venv .venv
+.venv/bin/python -m pip install -e '.[dev,docs]'
+npm ci
+.venv/bin/python -m pytest tests --ignore=tests/browser -q
+.venv/bin/python -m playwright install chromium
+.venv/bin/python -m pytest tests/browser -q
+npm run build:css
+npm run build:charts
+npm run build:icons
+npm run test:js
+```
+
+The npm commands are for developing NewAdmin's assets. Installing the Python
+package includes the compiled files and does not require Node.js.
+
+## Activate NewAdmin
+
+Add `newadmin` before Django's admin app. No model changes, middleware, or
+migrations are required in a consuming project:
+
+```python
+INSTALLED_APPS = [
+    "newadmin",
+    "django.contrib.admin",
+    # Other Django apps.
+]
+```
+
+The theme works with its defaults. Optional site branding and appearance can be
+set in `settings.py`:
+
+```python
+NEWADMIN = {
+    "SITE_TITLE": "Studio",
+    "SITE_HEADER": "Studio control room",
+    "DEFAULT_MODE": "auto",  # light, dark, or auto
+}
+```
+
+## Run the demo
+
+After installing the project in editable mode, prepare the sample catalog and
+create a local administrator:
+
+```sh
+.venv/bin/python demo/manage.py migrate
+.venv/bin/python demo/manage.py seed_demo
+.venv/bin/python demo/manage.py createsuperuser
+.venv/bin/python demo/manage.py runserver
+```
+
+Open <http://127.0.0.1:8000/admin/> and sign in with the account you created.
+The demo is a local development project and uses SQLite.
+
+See the [project specification](SPEC.md), [design](DESIGN.md), and
+[task list](tasks/todo.md) for scope and progress.
+
+## Custom dashboards
+
+Use a Python provider and a template to show data from your own models. Optional
+Apache ECharts graphs are bundled locally under Apache 2.0, with light/dark mode,
+responsive SVG output and an HTML data alternative. No chart license purchase or
+Node installation is required by a package consumer.
+
+See the [dashboard guide](docs/dashboard.md) for configuration, permissions,
+per-site providers, templates and examples. The demo enables an editorial provider
+with entry counts, category charts and recent articles.
+
+## Menus and extensions
+
+Configure model/app icons, named links with permission checks, per-AdminSite
+settings and custom CSS. Public template blocks let a consuming project extend
+the branding, sidebar and footer while retaining Django's native controls.
+See the [configuration and extension guide](docs/configuration.md).
+
+## Documentation (Sphinx)
+
+The Spanish user guides cover [installation](docs/installation.md),
+[configuration](docs/configuration.md), [dashboards](docs/dashboard.md),
+[accessibility](docs/accessibility.md) and [release steps](docs/releasing.md).
+Build the searchable HTML documentation locally:
+
+```sh
+.venv/bin/python -m sphinx -n -W --keep-going -b html docs docs/_build/html
+.venv/bin/python -m http.server 8002 --directory docs/_build/html
+```
+
+Open <http://127.0.0.1:8002/>. Read the [changelog](CHANGELOG.md) and alpha
+limitations before using this release. `.readthedocs.yaml` is ready for connecting
+a Read the Docs project; hosted documentation has not been published yet.

django_newadmin-0.1.0a1.dist-info/RECORD

@@ -0,0 +1,45 @@
+newadmin/__init__.py,sha256=FvmAOcUurKn1Z0X-SlNGQWJ0h0fWi84PWIxRFmOx8yg,85
+newadmin/apps.py,sha256=0evky5EuK_2OG4y4luj89dmQp7d1-c5-c0Iuqmy2b4U,320
+newadmin/checks.py,sha256=8TG2k3Q2YuI1j0ccYH8Vo5FPCZGPskPWT_E-NiZeZTc,1031
+newadmin/conf.py,sha256=dTyR5opDrFzDOoykzPXfQK5FfgnfNqO76bkgefU3R0Q,6683
+newadmin/dashboard.py,sha256=nxb578bQx4O9ddT0L-xJOQKZO8OIxWTsUgLBwi_GNaY,2646
+newadmin/navigation.py,sha256=ujUYpNaberxwFdtOt6hwIcVWMt-sVAjE0-SW-ene08c,1297
+newadmin/static/newadmin/icons.svg,sha256=4EaFfOnAGMrghpDb5OxVcHKHjF4R5ONPGrcj8-TU2g8,7895
+newadmin/static/newadmin/css/bootstrap.min.css,sha256=rFNjE8xYWt8O5lgisjZyrCR2HEbk7hVfCvg6vndd5JU,111217
+newadmin/static/newadmin/css/newadmin.css,sha256=YcvP3krRLLH2y6UIsurotUtJpOaTaB367ou4EszIuWM,68064
+newadmin/static/newadmin/js/accessibility.js,sha256=kOfM8SRh9X9xJlK6eTK2pT-lkyl9YtoBKzvJblmIlQE,2240
+newadmin/static/newadmin/js/appearance.js,sha256=4QKQnBYgH_oVjKO7bXJE0FYFLRE7o-LDP80OXAVuFDE,1614
+newadmin/static/newadmin/js/dashboard-charts.js,sha256=cscShtxQk1beAvD_GRt0z_3Un5W9wCZMPd44nZkrfPA,3827
+newadmin/static/newadmin/js/navigation.js,sha256=x92IO0oOllgW7OeU1xDwpA4-Iz6BeWFvAP4kjO11zxQ,1434
+newadmin/static/newadmin/vendor/bootstrap/LICENSE,sha256=RiDIStXOhgL_ZWQO1rfIt467ngNlhPDrwczIggaku1E,1093
+newadmin/static/newadmin/vendor/bootstrap-icons/LICENSE,sha256=D7PhG9V-iWxaUSr9ZIZNKKN95F0Zg1AWyHyhrRnq2Wk,1093
+newadmin/static/newadmin/vendor/django/LICENSE,sha256=uEZBXRtRTpwd_xSiLeuQbXlLxUbKYSn5UKGM0JHipmk,1552
+newadmin/static/newadmin/vendor/echarts/LICENSE,sha256=Y0KTg1tDpt0glPo5GCo9mmucpDt_25rDVOgDevKjCTo,11990
+newadmin/static/newadmin/vendor/echarts/NOTICE,sha256=1JHTWDRPhCaFwbFYWXCZnbZf4w7PfvOGeviBT0AWwBY,168
+newadmin/static/newadmin/vendor/echarts/echarts.min.js,sha256=tmslrrTfhOMxmdwhaUAU0zbSIsvZ3rDlp8FL1qoND9A,1121883
+newadmin/static/newadmin/vendor/echarts/licenses/LICENSE-d3,sha256=4SEYktoLDgWFt66-j5jBJ0-6Fbr-R_ofTuinpQLAYwQ,1475
+newadmin/static/newadmin/vendor/echarts/licenses/LICENSE-tslib,sha256=IQsZ5UMTA4jGhlS3SX6WcRnOFxRfZqt9hWiPvXDwh1E,655
+newadmin/static/newadmin/vendor/echarts/licenses/LICENSE-zrender,sha256=poHp0YPHK0r0hWk1iTgF60jAjw9aPyYCA9t0RMIPuYo,1509
+newadmin/static/newadmin/vendor/echarts/licenses/NOTICE-tslib,sha256=3YNeZ6mil9oy-UZ9dnel0CyOUOEPFdpDuBAUfHnAS5s,824
+newadmin/templates/admin/app_list.html,sha256=J2cYa3f1wXBGGQL6NUV0ay40WKE5WMoIIWZwc2t6J6g,2574
+newadmin/templates/admin/base.html,sha256=P-9eYps8lEUfunt9ZOgZZctyVlJd1zYnk45dJWfN2KI,783
+newadmin/templates/admin/base_site.html,sha256=YZMGGjgIadEjdJcFGLbOYYaye3MQ8DnOCUyoO9UlElY,1575
+newadmin/templates/admin/change_form.html,sha256=0M0jb1S3dST6BH5Z9e-VyyZ_0XqPARducTDxX97xi3o,114
+newadmin/templates/admin/change_list.html,sha256=q3LmE0KjobsX0Q7umZvAFEQEj_A9Js2Xj8fKrEcs_5c,547
+newadmin/templates/admin/filter.html,sha256=7eu-BQTi7IAx4b1ucJevliMCmLaGlbnrfYKrgJqi0Tc,419
+newadmin/templates/admin/index.html,sha256=XoZMLRLkzWhLDZHsMVn54o5xmlbcPDZ-Ivof5EfEdwQ,4712
+newadmin/templates/admin/nav_sidebar.html,sha256=wMA-YeMeugtq1rEEHli6TbOpYUM4a61OCPkAnvIS1O0,1403
+newadmin/templates/admin/object_history.html,sha256=kVCnXNr5ll7yx11IzNKktZG23pYeNKlEU59N6jxYbU0,120
+newadmin/templates/admin/auth/user/change_password.html,sha256=Gas4D1cbc8NCsNRN8fAak5lZ6mFkY7_LVJtOEL_aL1E,128
+newadmin/templates/newadmin/dashboard/chart.html,sha256=eSGM66YCzNlCNcmF4ecJefqzTMTGPz9IjJ-oyzpeQQo,1430
+newadmin/templates/newadmin/dashboard/editorial.html,sha256=ktz-9uZ2FMm3xUSbahGdVoJFohwKJcCj5lDT0oF7bP8,2525
+newadmin/templates/newadmin/dashboard/layout.html,sha256=ErWJE7MgDm5UufFU1-xTOCppCsyZa02kcUGmAte9q2Q,978
+newadmin/templates/newadmin/dashboard/metric.html,sha256=UudPFXpxSX4XnVbzecKW3DcbIE66AiEm3jj8Wzvi0jU,417
+newadmin/templates/registration/password_change_done.html,sha256=sKqLpoJ6Q1sLgMissaq3ry_hVcIdXyXdqlKWakWzlmk,139
+newadmin/templates/registration/password_change_form.html,sha256=kwPbtL2S508kCCOwa-sahXqH_sFDGG9GOKF7WlG3rbU,130
+newadmin/templatetags/__init__.py,sha256=w-XVzoWOfsQvMW4MJikPlJgXbxZQGrNaygE0uNcEFpU,30
+newadmin/templatetags/newadmin.py,sha256=UcxtYTaemko27X_fNOM29YGq_0jV5GQvITLTJVijt0o,2487
+django_newadmin-0.1.0a1.dist-info/METADATA,sha256=IfbmgKM_t6vu3ChBv-75xYwrEnJSaNHIemJ9V8BBOiQ,5089
+django_newadmin-0.1.0a1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+django_newadmin-0.1.0a1.dist-info/licenses/LICENSE,sha256=s3-nmFNTc-wUV0h3j87sq0EOzgHGTHMdIFnX8IqtzjA,1532
+django_newadmin-0.1.0a1.dist-info/RECORD,,

django_newadmin-0.1.0a1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

django_newadmin-0.1.0a1.dist-info/licenses/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, CARocha and contributors
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software without
+   specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

newadmin/__init__.py

@@ -0,0 +1,3 @@
+"""Modern, extensible theme for Django's built-in admin."""
+
+__version__ = "0.1.0a1"

newadmin/apps.py

@@ -0,0 +1,13 @@
+"""Application definition for the NewAdmin theme."""
+
+from django.apps import AppConfig
+
+
+class NewAdminConfig(AppConfig):
+    """Register NewAdmin as a lightweight Django application."""
+
+    name = "newadmin"
+    verbose_name = "Django NewAdmin"
+
+    def ready(self):
+        from newadmin import checks  # noqa: F401

newadmin/checks.py

@@ -0,0 +1,28 @@
+"""Django system checks for common NewAdmin configuration errors."""
+
+from django.conf import settings
+from django.core.checks import Error, register
+from django.core.exceptions import ImproperlyConfigured
+
+from newadmin.conf import get_options
+
+
+@register("admin")
+def check_newadmin(app_configs, **kwargs):
+    errors = []
+    installed_apps = getattr(settings, "INSTALLED_APPS", [])
+    if "newadmin" in installed_apps and "django.contrib.admin" in installed_apps:
+        if installed_apps.index("newadmin") > installed_apps.index("django.contrib.admin"):
+            errors.append(
+                Error(
+                    "Add 'newadmin' before 'django.contrib.admin' in INSTALLED_APPS.",
+                    id="newadmin.E005",
+                )
+            )
+    try:
+        options = get_options()
+        for site_name in options["SITES"]:
+            get_options(site_name)
+    except ImproperlyConfigured as exc:
+        errors.append(Error(str(exc), id=getattr(exc, "check_id", "newadmin.E002")))
+    return errors

newadmin/conf.py

@@ -0,0 +1,168 @@
+"""Validated settings for NewAdmin."""
+
+from collections.abc import Mapping
+from copy import deepcopy
+
+from django.conf import settings
+from django.core.exceptions import ImproperlyConfigured
+from django.utils.functional import Promise
+
+DEFAULTS = {
+    "SITE_TITLE": None,
+    "SITE_HEADER": None,
+    "LOGO": None,
+    "DEFAULT_MODE": "auto",
+    "PALETTE": "sapphire",
+    "MENU": {"ORDER": [], "ICONS": {}, "LINKS": []},
+    "CUSTOM_CSS": [],
+    "DASHBOARD": None,
+    "SITES": {},
+}
+VALID_MODES = {"light", "dark", "auto"}
+ICON_NAMES = {
+    "grid",
+    "file-text",
+    "users",
+    "settings",
+    "folder",
+    "image",
+    "calendar",
+    "chart",
+    "tag",
+    "database",
+    "globe",
+    "link",
+}
+
+
+class _SettingsError(ImproperlyConfigured):
+    check_id = "newadmin.E001"
+
+
+class _ResourceError(ImproperlyConfigured):
+    check_id = "newadmin.E003"
+
+
+class _MenuError(ImproperlyConfigured):
+    check_id = "newadmin.E004"
+
+
+def _merge(base, overrides):
+    result = deepcopy(base)
+    for key, value in overrides.items():
+        if key in result and isinstance(result[key], dict) and isinstance(value, Mapping):
+            result[key] = _merge(result[key], value)
+        else:
+            result[key] = deepcopy(value)
+    return result
+
+
+def _validate_resource_path(value, option):
+    if value is None and option == "LOGO":
+        return
+    paths = [value] if option == "LOGO" else value
+    if option == "CUSTOM_CSS" and not isinstance(paths, list):
+        raise _ResourceError("NEWADMIN.CUSTOM_CSS must be a list of static paths.")
+    for path in paths:
+        if (
+            not isinstance(path, str)
+            or not path
+            or path.startswith(("/", "\\"))
+            or ".." in path.split("/")
+            or "\\" in path
+            or any(char in path for char in (":", "?", "#"))
+        ):
+            raise _ResourceError(f"NEWADMIN.{option} must contain safe relative static paths.")
+
+
+def get_options(site_name=None):
+    """Return a fresh, validated settings mapping for an optional AdminSite."""
+    raw = getattr(settings, "NEWADMIN", {})
+    if not isinstance(raw, Mapping):
+        raise _SettingsError("NEWADMIN must be a mapping of supported options.")
+    unknown = set(raw) - set(DEFAULTS)
+    if unknown:
+        raise ImproperlyConfigured(
+            f"Unknown NEWADMIN option(s): {', '.join(sorted(map(str, unknown)))}."
+        )
+
+    options = _merge(DEFAULTS, raw)
+    if not isinstance(options["SITES"], Mapping):
+        raise _SettingsError("NEWADMIN.SITES must be a mapping of AdminSite names to options.")
+    if site_name is not None and site_name in options["SITES"]:
+        site_options = options["SITES"][site_name]
+        if not isinstance(site_options, Mapping):
+            raise _SettingsError(f"NEWADMIN.SITES.{site_name} must be a mapping.")
+        unknown_site = set(site_options) - (set(DEFAULTS) - {"SITES"})
+        if unknown_site:
+            raise ImproperlyConfigured(
+                f"Unknown NEWADMIN.SITES.{site_name} option(s): "
+                f"{', '.join(sorted(map(str, unknown_site)))}."
+            )
+        options = _merge(options, site_options)
+
+    if not isinstance(options["DEFAULT_MODE"], str) or options["DEFAULT_MODE"] not in VALID_MODES:
+        raise ImproperlyConfigured("NEWADMIN.DEFAULT_MODE must be 'light', 'dark', or 'auto'.")
+    if options["PALETTE"] != "sapphire":
+        raise ImproperlyConfigured("NEWADMIN.PALETTE must be 'sapphire'.")
+    _validate_resource_path(options["LOGO"], "LOGO")
+    _validate_resource_path(options["CUSTOM_CSS"], "CUSTOM_CSS")
+    if options["DASHBOARD"] is not None and (
+        not isinstance(options["DASHBOARD"], str) or not options["DASHBOARD"].strip()
+    ):
+        raise ImproperlyConfigured("NEWADMIN.DASHBOARD must be an importable class path or None.")
+    if not isinstance(options["MENU"], Mapping):
+        raise _MenuError("NEWADMIN.MENU must be a mapping.")
+    menu_keys = {"ORDER", "ICONS", "LINKS"}
+    unknown_menu_keys = set(options["MENU"]) - menu_keys
+    if unknown_menu_keys:
+        raise _MenuError(
+            f"Unknown NEWADMIN.MENU option(s): {', '.join(sorted(map(str, unknown_menu_keys)))}."
+        )
+    order = options["MENU"].get("ORDER", [])
+    if not isinstance(order, list) or any(not isinstance(label, str) for label in order):
+        raise _MenuError("NEWADMIN.MENU.ORDER must be a list of app labels.")
+    if len(order) != len(set(order)):
+        raise _MenuError("NEWADMIN.MENU.ORDER cannot contain duplicate app labels.")
+    icons = options["MENU"].get("ICONS", {})
+    if not isinstance(icons, Mapping):
+        raise _MenuError("NEWADMIN.MENU.ICONS must map app/model names to icon names.")
+    for key, icon in icons.items():
+        if (
+            not isinstance(key, str)
+            or not key
+            or not isinstance(icon, str)
+            or icon not in ICON_NAMES
+        ):
+            raise _MenuError(f"NEWADMIN.MENU.ICONS.{key} must use a supported icon name.")
+    links = options["MENU"].get("LINKS", [])
+    if not isinstance(links, list):
+        raise _MenuError("NEWADMIN.MENU.LINKS must be a list of link mappings.")
+    for index, link in enumerate(links):
+        path = f"NEWADMIN.MENU.LINKS[{index}]"
+        if not isinstance(link, Mapping):
+            raise _MenuError(f"{path} must be a mapping.")
+        unknown_link = set(link) - {"LABEL", "URL_NAME", "ICON", "PERMISSIONS"}
+        if unknown_link:
+            raise _MenuError(
+                f"{path} has unknown option(s): {', '.join(sorted(map(str, unknown_link)))}."
+            )
+        for key in ("LABEL", "URL_NAME"):
+            types = (str, Promise) if key == "LABEL" else str
+            if not isinstance(link.get(key), types) or not str(link[key]).strip():
+                raise _MenuError(f"{path}.{key} must be non-empty text.")
+        if "ICON" in link and (not isinstance(link["ICON"], str) or link["ICON"] not in ICON_NAMES):
+            raise _MenuError(f"{path}.ICON must name a supported icon.")
+        permissions = link.get("PERMISSIONS", [])
+        if not isinstance(permissions, list) or any(
+            not isinstance(permission, str)
+            or permission.count(".") != 1
+            or not all(permission.split("."))
+            or any(char.isspace() for char in permission)
+            for permission in permissions
+        ):
+            raise _MenuError(f"{path}.PERMISSIONS must be a list of app.codename values.")
+    for name in ("SITE_TITLE", "SITE_HEADER"):
+        if options[name] is not None and not isinstance(options[name], str):
+            raise ImproperlyConfigured(f"NEWADMIN.{name} must be text or None.")
+    return options

newadmin/dashboard.py

@@ -0,0 +1,72 @@
+"""Request-scoped extension point for the admin's main dashboard."""
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+from django.core.exceptions import ImproperlyConfigured
+from django.forms import Media
+from django.forms.widgets import MediaDefiningClass
+from django.utils.module_loading import import_string
+
+from newadmin.conf import get_options
+
+
+class Dashboard(metaclass=MediaDefiningClass):
+    """Provide a template, request data and optional Media for the admin index."""
+
+    template_name = "newadmin/dashboard/layout.html"
+    permissions = ()
+
+    def has_permission(self, request):
+        return (
+            request.user.is_active
+            and request.user.is_staff
+            and request.user.has_perms(self.permissions)
+        )
+
+    def get_context_data(self, request):
+        return {}
+
+
+class EChartsDashboard(Dashboard):
+    """Opt in to the packaged, local Apache ECharts runtime and adapter."""
+
+    class Media:
+        js = ["newadmin/vendor/echarts/echarts.min.js", "newadmin/js/dashboard-charts.js"]
+
+
+@dataclass
+class _ResolvedDashboard:
+    template_name: str
+    data: Mapping
+    media: Media
+
+
+def resolve_dashboard(request):
+    """Resolve once per request; permission checks precede data and Media evaluation."""
+    if hasattr(request, "_newadmin_dashboard"):
+        return request._newadmin_dashboard
+    site_name = getattr(request, "current_app", None) or getattr(
+        getattr(request, "resolver_match", None), "namespace", None
+    )
+    path = get_options(site_name)["DASHBOARD"]
+    result = None
+    if path is not None:
+        try:
+            provider_class = import_string(path)
+        except (ImportError, AttributeError) as exc:
+            raise ImproperlyConfigured(f"NEWADMIN.DASHBOARD cannot import {path!r}.") from exc
+        if not isinstance(provider_class, type) or not issubclass(provider_class, Dashboard):
+            raise ImproperlyConfigured("NEWADMIN.DASHBOARD must name a Dashboard subclass.")
+        provider = provider_class()
+        if provider.has_permission(request):
+            data = provider.get_context_data(request)
+            if not isinstance(data, Mapping):
+                raise ImproperlyConfigured("NEWADMIN.DASHBOARD context must be a mapping.")
+            if not isinstance(provider.template_name, str) or not provider.template_name:
+                raise ImproperlyConfigured(
+                    "NEWADMIN.DASHBOARD template_name must be non-empty text."
+                )
+            result = _ResolvedDashboard(provider.template_name, data, provider.media)
+    request._newadmin_dashboard = result
+    return result

newadmin/navigation.py

@@ -0,0 +1,37 @@
+"""Request-specific navigation derived from the active admin site."""
+
+from django.core.exceptions import ImproperlyConfigured
+from django.urls import NoReverseMatch, reverse
+from django.utils.encoding import iri_to_uri
+
+from newadmin.conf import get_options
+
+
+def site_name(request):
+    match = getattr(request, "resolver_match", None)
+    return getattr(request, "current_app", None) or getattr(match, "namespace", None)
+
+
+def custom_links(request):
+    name = site_name(request)
+    options = get_options(name)
+    user = getattr(request, "user", None)
+    links = []
+    for index, item in enumerate(options["MENU"]["LINKS"]):
+        if item.get("PERMISSIONS") and (user is None or not user.has_perms(item["PERMISSIONS"])):
+            continue
+        try:
+            url = reverse(item["URL_NAME"], current_app=name)
+        except NoReverseMatch as exc:
+            raise ImproperlyConfigured(
+                f"NEWADMIN.MENU.LINKS[{index}].URL_NAME cannot be resolved: {item['URL_NAME']!r}."
+            ) from exc
+        links.append(
+            {
+                "label": item["LABEL"],
+                "url": url,
+                "icon": item.get("ICON", "link"),
+                "current": iri_to_uri(getattr(request, "path", "")) == url,
+            }
+        )
+    return links