Metadata-Version: 2.4
Name: ocyan.plugin.admin-theme
Version: 0.1.0rc3
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. In a conventional
Django project, 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.

In an Ocyan project, include `ocyan.plugin.admin-theme` in `ocyan.json`.
The package's Ocyan entry point adds its Django app and prepends its packaged
template directory to Ocyan's filesystem-first template loader. This is
necessary because that loader has its own extension ordering; projects must
not duplicate the theme's templates or add a second Django-admin app entry.

### Namespace compatibility status

This distribution uses the `ocyan.plugin` namespace and is intentionally
independent of `ocyan.main`. Its Ocyan entry point is lazy, so ordinary Django
projects do not need Ocyan runtime integration merely to import or use the
theme through `INSTALLED_APPS`.

## 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.
