Metadata-Version: 2.4
Name: ocyan.plugin.admin-theme
Version: 0.1.0rc1
Summary: Reusable, accessible Django administration presentation theme
Author-email: MandelBlog <info@mandelblog.com>
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://git.mandelblog.com/mandel-plugins/ocyan.plugin.admin_theme
Project-URL: Repository, https://git.mandelblog.com/mandel-plugins/ocyan.plugin.admin_theme
Project-URL: Documentation, https://git.mandelblog.com/mandel-plugins/ocyan.plugin.admin_theme
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Framework :: Django :: 5.2
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Requires-Python: <3.14,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Django<6,>=5.2
Dynamic: license-file

# Ocyan Admin Theme

`ocyan.plugin.admin-theme` is an opt-in, reusable presentation layer for
Django administration. It themes Django admin templates and static assets; it
does not replace Django authentication, permissions, routes, model
registration, or Wagtail administration.

## Repository structure

This is a first-class Ocyan plugin repository. It follows the current,
modernised plugin form: source in `src/`, PEP 621 metadata in `pyproject.toml`,
namespaced package data, focused Django tests, a changelog, and a
source-controlled non-deploying `Jenkinsfile`. Older Ocyan plugins commonly
use a flat `setup.py` layout; this package deliberately does not copy that
legacy structure.

## Install and activate

Install the package as an explicit project dependency. Add the app before
`django.contrib.admin` so Django’s app-template discovery selects the theme:

```python
INSTALLED_APPS = [
    "ocyan.plugin.admin_theme",
    "django.contrib.admin",
    # remaining applications
]
```

Leaving the app out intentionally preserves standard Django administration.
`ocyan.main` does not require this package.

### Namespace compatibility status

This distribution uses Python's native (PEP 420) `ocyan.plugin` namespace.
It is intentionally independent of `ocyan.main`. A host can use it only when
the installed `ocyan` and `ocyan.plugin` parent packages are also
PEP-420-compatible. The current legacy MandelBlogStack parent distributions
still use `pkg_resources.declare_namespace`, which prevents Python from
discovering this package in the same environment. That family-wide namespace
modernisation is a prerequisite for MandelStudio integration and RC release;
this package does not ship compatibility shims that would perpetuate the old
namespace mechanism.

## Branding

Projects configure their own identity; this package deliberately ships no
project logo or private asset.

```python
OCYAN_ADMIN_THEME = {
    "company_name": "MandelBlog",
    "product_name": "Operations Platform",
    "compact_logo": "M",
    "logo_url": "/static/project/brand/logo.svg",
    "logo_dark_url": "/static/project/brand/logo-dark.svg",
    "compact_logo_url": "/static/project/brand/icon.svg",
    "compact_logo_dark_url": "/static/project/brand/icon-dark.svg",
    "favicon_url": "/static/project/brand/favicon.svg",
    "application_icon_url": "/static/project/brand/icon.svg",
    "login_heading": "Welcome back",
    "login_supporting_text": "Manage your authorised operations from one place.",
    "accent_color": "#1769aa",
}
```

Branding URLs accept root-relative paths or explicit HTTP(S) URLs only.
Prefer project-owned SVG assets for crisp high-DPI rendering. The package has
safe text/mark fallbacks if no assets are configured.

## Compatibility and accessibility

The initial release line supports Python 3.12 and Django 5.2 through 5.x.
It has no Wagtail dependency and can coexist with Wagtail because it only
overrides Django-admin templates. It uses native form labels, Django’s CSRF
form flow, visible focus treatments, reduced-motion handling, and forced
colours fallbacks.

Run the test suite with:

```shell
DJANGO_SETTINGS_MODULE=tests.settings python -m django test tests
```

Build artifacts with:

```shell
python -m build
```

Before an RC, test a built wheel and sdist in clean environments and run a
project integration test with the theme both enabled and intentionally absent.

## Scope and fallback

The package themes Django administration only. It does not replace Django
authentication, routing, permissions, model registration, or Wagtail admin.
Projects can opt out by removing the app from `INSTALLED_APPS`; standard Django
admin templates then remain in use.
