Metadata-Version: 2.4
Name: mandel-plugin-template-engine
Version: 0.1.0.dev0
Summary: Mandel vNext composable block engine for Wagtail and Django Oscar.
Author: Mandel
License-Expression: LicenseRef-Proprietary
Project-URL: Repository, https://git.mandelblog.com/mandel-plugins/mandel.plugin.template_engine
Requires-Python: <3.13,>=3.12
Description-Content-Type: text/markdown
Requires-Dist: Django<5.3,>=5.2
Requires-Dist: Wagtail<7.5,>=7.4.3
Provides-Extra: commerce
Requires-Dist: django-oscar<4.2,>=4.1; extra == "commerce"
Provides-Extra: test
Requires-Dist: pytest<9,>=8; extra == "test"
Requires-Dist: ruff<0.13,>=0.12; extra == "test"
Requires-Dist: build<2,>=1.2; extra == "test"

# Mandel Template Engine

Mandel Template Engine is the vNext reusable block capability layer for Mandel websites and webshops.
It is deliberately separate from visual providers.

## Responsibilities

- Wagtail owns editorial composition.
- Django Oscar is optional and is required only by commerce blocks.
- Theme providers own presentation.
- This plugin owns block contracts, capability filtering, site activation, provider renderer resolution,
  neutral fallback rendering, and validation.

## Host modes

- `CONTENT`: website/content blocks plus universal blocks.
- `COMMERCE`: webshop/commerce blocks plus universal blocks.
- `HYBRID`: content, commerce, and universal blocks.
- `AUTO`: derives the mode from installed capabilities. Oscar present means hybrid; otherwise content.

## Renderer resolution

For every block the engine resolves rendering explicitly:

1. provider-native renderer registered for the active provider;
2. neutral renderer owned by this plugin;
3. fail closed if a block requires provider-native rendering and no renderer is registered.

There is no provider capability discovery by accidental Django template-loader precedence.

## Kroon clean-room redesign

The Kroon showcase slider idea is represented by `showcase_carousel`, a universal content block.
The Kroon product slider idea is represented separately by `product_carousel`, a commerce-only block.
No Kroon, Coyote, Cabasa, Oxyan, or Ocyan runtime dependency is imported by this package.

## Install

```bash
uv add mandel-plugin-template-engine
```

Add the app:

```python
INSTALLED_APPS += ["mandel.plugin.template_engine"]
```

Run migrations after installing the package into a Django/Wagtail host.

For an existing page model, define its StreamField with `streamfield_definitions()` and use
`MandelBlockPageForm` as the page form. A complete integration example is in
`docs/INTEGRATION.md`.

## Provider integration

Provider packages register explicit renderer maps through the
`mandel.template_engine.renderers` entry-point group or by calling
`register_provider_bundle()`. See `docs/PROVIDER_INTEGRATION.md`.

## Compatibility target

- Python 3.12
- Django 5.2.x
- Wagtail 7.4.x
- Django Oscar 4.1.x when commerce is enabled
- Bootstrap 5 neutral fallback templates

## Build status

See [`docs/IMPLEMENTATION_STATUS.md`](docs/IMPLEMENTATION_STATUS.md) for implemented scope and the remaining runtime-certification gate.
