django-jsonsson 0.1.2__tar.gz

django_jsonsson-0.1.2/.github/workflows/ci.yaml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  black:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v6
+      - run: make lint
+
+  tests:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        include:
+          - python: "3.10"
+            django: "4.2"
+          - python: "3.12"
+            django: "5.2"
+          - python: "3.14"
+            django: "6.0"
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv run --extra dev --with "django~=${{ matrix.django }}.0" pytest

django_jsonsson-0.1.2/.github/workflows/release.yaml

@@ -0,0 +1,74 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    env:
+      TAG: ${{ github.event.release.tag_name }}
+    steps:
+      # hatch-vcs reads the version from the git tag, so it needs the tags.
+      - name: Check out the tag
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ env.TAG }}
+          fetch-depth: 0
+
+      - uses: astral-sh/setup-uv@v6
+
+      - name: Check the tag format
+        run: |
+          if ! [[ "$TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "::error::Tag $TAG isn't in vX.Y.Z format"
+            exit 1
+          fi
+
+      - name: Lint
+        run: make lint
+
+      - name: Test
+        run: uv run --extra dev pytest
+
+      - name: Build
+        run: uv build
+
+      # A dirty tree or a wrong checkout gives a .devN version instead.
+      - name: Check the built version matches the tag
+        run: ls "dist/django_jsonsson-${TAG#v}-py3-none-any.whl" "dist/django_jsonsson-${TAG#v}.tar.gz"
+
+      - name: Check the wheel has templates and static files
+        run: |
+          files=$(unzip -l dist/*.whl)
+          grep -q "jsonsson/templates/jsonsson/widgets/list.html" <<< "$files"
+          grep -q "jsonsson/static/jsonsson/js/list.js" <<< "$files"
+          grep -q "jsonsson/static/jsonsson/css/list.css" <<< "$files"
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  # Separate job, so only the upload step gets the OIDC token.
+  # Uses PyPI trusted publishing, no API token is stored in the repo.
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/django-jsonsson
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

django_jsonsson-0.1.2/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/

django_jsonsson-0.1.2/AGENTS.md

@@ -0,0 +1,121 @@
+# django-jsonsson - AI Agent Guide
+
+Reusable Django form widgets that render `JSONField` values as plain, editable inputs. Install name `django-jsonsson`, import name `jsonsson`.
+
+User-facing docs live in `README.md`. This file is for working on the library itself.
+
+> **Self-update rule**: after finishing a task, ask "would a future agent get this wrong without knowing what I just learned?" If yes, update this file in the same changeset. Add gotchas, corrected assumptions, new build or release steps, new conventions. Don't add ticket-specific details or temporary workarounds. If the change is visible to users (new widget, new option, changed behavior), update `README.md` too.
+
+## Tech Stack
+
+| Layer | Technology |
+|-------|-----------|
+| Language | Python 3.10+ |
+| Framework | Django 4.2+ (CI: 4.2, 5.2, 6.0) |
+| Frontend | Plain ES5-style JS and CSS, no build step, no dependencies |
+| Build backend | `hatchling` (src layout) |
+| Package manager | `uv` |
+| Tests | `pytest` + `pytest-django` |
+| Formatter | `black` (enforced in CI) |
+
+## Layout
+
+```
+src/jsonsson/
+  __init__.py                          # public API (re-exports widgets), __version__ from package metadata
+  apps.py                              # JsonssonConfig, only so templates/static are found
+  widgets.py                           # ListWidget
+  templates/jsonsson/widgets/list.html # ListWidget markup
+  static/jsonsson/js/list.js           # builds inputs, syncs JSON back to the textarea
+  static/jsonsson/css/list.css         # layout only
+tests/
+  settings.py                          # Django settings for pytest (admin, sessions, messages)
+  urls.py                              # admin URLs, used by test_admin.py
+  testapp/                             # sample ports editor in an admin inline (models + admin)
+  test_list_widget.py
+  test_admin.py                        # ListWidget through the real admin
+.github/workflows/ci.yaml              # black + pytest matrix
+```
+
+## How a widget works
+
+Every widget follows the same pattern. Keep it for new widgets.
+
+1. **Python** (`widgets.py`): a `forms.Textarea` subclass. `get_context()` adds the `jsonsson-<widget>-source` class and `display:none` to the textarea, then puts the widget's options under `context["widget"]["jsonsson"]`.
+2. **Template** (`templates/jsonsson/widgets/<widget>.html`): an outer container with the options as `data-*` attributes, the stock `django/forms/widgets/textarea.html` included inside it, plus any static controls (the add button).
+3. **JS** (`static/jsonsson/js/<widget>.js`): finds containers, reads `data-*`, parses the textarea's JSON, builds inputs, and writes `JSON.stringify(...)` back into the textarea on every change.
+4. **Backend**: Django only ever sees the textarea. The browser never coerces types. Converting and validating is the host form's `clean_<field>()`.
+
+The Python -> template -> JS contract for `ListWidget`:
+
+| Python (`widget.jsonsson`) | HTML | JS reads |
+|---------------------------|------|----------|
+| `block` | `jsonsson-list--block` class | (CSS only) |
+| `min_items` | `data-min-items` | `editor.dataset.minItems` |
+| `remove_label` | `data-remove-label` | `editor.dataset.removeLabel` |
+| `input_attrs` (JSON string) | `data-input-attrs` | `JSON.parse(editor.dataset.inputAttrs)` |
+| `add_label`, `add_text` | add button `title`/`aria-label`/text | (static markup) |
+
+Changing any name means changing all three places, plus the README tables.
+
+## Adding a new widget
+
+1. Add the class to `widgets.py`, and export it from `__init__.py` (`__all__` too).
+2. Add `templates/jsonsson/widgets/<name>.html`, `static/jsonsson/js/<name>.js`, `static/jsonsson/css/<name>.css`, and declare the assets in the widget's `Media`.
+3. Prefix every CSS class and data attribute with `jsonsson-<name>`. Wrap the JS in an IIFE and use a namespaced init flag (`dataset.jsonssonInit`-style) so it's idempotent.
+4. Handle `DOMContentLoaded` and `formset:added`, and skip elements whose source `name` contains `__prefix__` (the admin's empty formset template row).
+5. Add tests (see below) and document it in `README.md` (widgets table, options, CSS classes, template context).
+
+## Conventions
+
+- **Namespacing**: all CSS classes, data attributes, template paths and static paths start with `jsonsson`. This is a library that lands in someone else's project, so nothing generic like `.list-editor` or `admin/js/...`.
+- **Markup in templates, not Python strings**: users override `jsonsson/widgets/*.html`. Escaping comes from template autoescape. Don't go back to `mark_safe(f"...")`.
+- **CSS is layout only**: spacing and show/hide. Sizing and colors belong to the host project, which adds its own CSS via a subclass `Media` (Django merges it with ours).
+- **Inputs never restrict typing**: generated inputs are always plain `<input type="text">`. `mode`/`value_type` are backend hints only and must never change rendering. Restrictions go through `input_attrs`, which the user sets on purpose.
+- **Submitted values are always strings**: trimmed, empty ones dropped. Don't add type coercion in JS.
+- **Option resolution order** (`ListWidget.__init__`): constructor kwarg, then class attribute, then the `MODES` preset, then the hardcoded default. `value_type` and `input_attrs` default to `None` on the class precisely so this fallback works. Keep it when adding options.
+- **Mutable defaults**: `input_attrs` must end up a fresh dict per instance, including when it comes from a class attribute. `__init__` copies it, and `__deepcopy__` copies it again because Django deep-copies widgets per form (`Meta.widgets`) and `Widget.__deepcopy__` only copies `attrs`.
+- **Public API** is whatever `jsonsson/__init__.py` exports, plus the template context keys and CSS class names documented in the README. Treat changes to any of them as breaking.
+
+## Gotchas
+
+- **Widget `attrs` merge**: `get_context()` merges `self.attrs` with the passed `attrs` *before* appending our class and style. Django's own `build_attrs()` lets passed attrs replace widget attrs, so without this merge a `class`/`style` given to the constructor is silently dropped. Covered by `test_render_keeps_caller_class_and_style`.
+- **`input_attrs` are DOM properties**: `list.js` does `input[key] = value`, not `setAttribute()`. So keys must be JS property names (`maxLength`, `readOnly`). `maxlength` silently does nothing.
+- **`null` value breaks the JS**: `forms.JSONField.prepare_value(None)` renders `null`, `JSON.parse` returns `null`, and `initEditor()` throws on `values.length`. Same for a JSON object. Documented as a README limitation. If you fix it, update the README too.
+- **Admin icon path**: `list.css` points at `url(../../admin/img/icon-addlink.svg)`, relative to `static/jsonsson/css/`, so it resolves to `STATIC_URL/admin/img/...`. It only exists when `django.contrib.admin` is installed. `--border-color` (an admin CSS variable) has a `#ccc` fallback. Don't make the library depend on the admin beyond that.
+- **Template lookup**: the widget template is found through the form renderer's app-dirs lookup, which is why `jsonsson` has to be in `INSTALLED_APPS`. Tests rely on that too (`tests/settings.py`).
+- **`uv` picking the wrong venv**: if the shell has `VIRTUAL_ENV` set from another project, `uv` warns and ignores it. Run `unset VIRTUAL_ENV` if anything looks odd.
+
+## Testing
+
+```bash
+make test        # uv sync --extra dev + pytest
+make lint        # black --check
+make fmt         # black
+```
+
+- Tests are pure Python: options and fallbacks, rendered HTML (classes, `data-*`, escaping, attrs merging), form round trip through `forms.JSONField`, `Media`, and that static files are found.
+- **Admin integration**: `tests/testapp/admin.py` is a typical setup, a `PortsListWidget` on a `Service.ports` JSONField in an admin `TabularInline`. `tests/test_admin.py` covers it through the real admin: class-attribute options, subclass `Media` merging (host CSS after ours), `Meta.widgets` copies, rendering existing int lists and the `__prefix__` row, and posting string lists that `clean_ports()` turns into ints. If one of these fails, the change will likely break real projects. Don't loosen the test, either fix the change or treat it as breaking.
+- There are **no JS tests**. Any change to `list.js` or `list.css` needs a manual browser check: add, remove, `min_items` hiding the remove buttons, the hidden textarea's value after each change, and a row added through an admin inline formset.
+- Assert on the exact rendered markup or behavior, not just "renders without error". A wrong template branch still renders fine.
+- To check an older Django version locally, like CI does:
+
+  ```bash
+  uv run --isolated --extra dev --python 3.12 --with "django~=4.2.0" pytest
+  ```
+
+## Release
+
+Releases go to PyPI as `django-jsonsson`. The license is MIT (`LICENSE`, declared via `license`/`license-files` in `pyproject.toml`, which needs `hatchling>=1.27`).
+
+The version is never written in the code. `hatch-vcs` takes it from the git tag at build time, and `__version__` reads it back from the installed package metadata. Between tags, builds get a `.devN` version (e.g. `0.1.2.dev3+g1a2b3c4`), which is expected.
+
+1. Merge everything to `main`.
+2. Publish a GitHub release tagged `v<version>` (e.g. `v0.2.0`) from `main`.
+3. `.github/workflows/release.yaml` runs on `release: published`. It checks out the tag with full history (hatch-vcs needs the tags), fails if the tag isn't `vX.Y.Z`, runs lint and tests, builds with `uv build`, checks the built files have exactly the tag's version and the wheel has `templates/` and `static/`, then a separate `publish` job uploads the wheel and sdist to PyPI.
+
+Publishing uses PyPI trusted publishing (OIDC), so there's no API token secret. It needs a trusted publisher on PyPI for this repo, workflow `release.yaml` and environment `pypi`, plus a `pypi` environment in the GitHub repo settings. If the repo, workflow file or environment is renamed, update the PyPI side too or the upload fails. A version can only be uploaded to PyPI once, so a failed release after upload needs a version bump, not a re-run.
+
+A release created by another workflow with `GITHUB_TOKEN` won't trigger it (GitHub doesn't fire events for those). If you add such a workflow, call `release.yaml` through `workflow_call`.
+
+Consumers install it with `pip install django-jsonsson` and pin versions as usual.

django_jsonsson-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pavlo K.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

django_jsonsson-0.1.2/Makefile

@@ -0,0 +1,21 @@
+.PHONY: help install-dev test fmt lint build
+
+.DEFAULT_GOAL := help
+
+help: ## Show this help message
+	@grep -E '^[a-zA-Z_-]+:.*##' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*##"}; {printf "  \033[36m%-12s\033[0m %s\n", $$1, $$2}'
+
+install-dev: ## Install all dependencies (including dev)
+	uv sync --extra dev
+
+test: install-dev ## Run tests
+	uv run pytest
+
+fmt: ## Format code with black
+	uv run --extra dev black src tests
+
+lint: ## Check formatting (CI)
+	uv run --extra dev black --check src tests
+
+build: ## Build sdist and wheel into dist/
+	uv build

django_jsonsson-0.1.2/PKG-INFO

@@ -0,0 +1,281 @@
+Metadata-Version: 2.5
+Name: django-jsonsson
+Version: 0.1.2
+Summary: Django form widgets that turn JSONField values into plain, editable inputs.
+Author: Pavlo K.
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.2
+Classifier: Framework :: Django :: 6.0
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: django>=4.2
+Provides-Extra: dev
+Requires-Dist: black; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-django; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Jsonsson
+
+Django form widgets that show a `JSONField` value as plain, editable inputs instead of a raw JSON textarea.
+
+Nobody likes typing `["80", "443"]` by hand into a textarea. With Jsonsson the user gets one input per value, a button to add more and a cross to remove one. The form still submits normal JSON, so your model, form field and validation don't change.
+
+## How it works
+
+The real form field is still there, rendered as a hidden `<textarea>` with the JSON value inside. A small script reads that JSON, builds the inputs from it, and writes the JSON back into the textarea on every change. Django never sees the generated inputs, only the textarea.
+
+This means:
+
+- Works with Django's own `forms.JSONField` and `models.JSONField`, no custom field needed.
+- Validation and type conversion stay on the backend, in your form's `clean_<field>()`.
+- No build step and no frontend dependencies. Plain JS and CSS.
+
+## Widgets
+
+| Widget | JSON shape | Example value |
+|--------|------------|---------------|
+| `ListWidget` | Flat list of scalar values | `["80", "443"]` |
+
+More JSON shapes (objects, single values) are planned.
+
+## Requirements
+
+- Python 3.10+
+- Django 4.2+
+- `django.contrib.admin` is optional, but the bundled CSS uses its add icon and colors (see [Styling](#styling)).
+
+## Install
+
+```bash
+pip install django-jsonsson
+# or
+uv add django-jsonsson
+```
+
+Add the app to `INSTALLED_APPS`, so Django can find its templates and static files:
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "jsonsson",
+]
+```
+
+The widget's JS and CSS are declared in its `Media`. The Django admin includes them automatically. In your own templates, render `{{ form.media }}` like for any other widget with assets.
+
+## ListWidget
+
+### Quick start
+
+A model with a list field:
+
+```python
+from django.db import models
+
+
+class Service(models.Model):
+    name = models.CharField(max_length=100)
+    tags = models.JSONField(default=list, blank=True)
+```
+
+Use the widget in a form:
+
+```python
+from django import forms
+from jsonsson import ListWidget
+
+
+class ServiceForm(forms.ModelForm):
+    class Meta:
+        model = Service
+        fields = "__all__"
+        widgets = {"tags": ListWidget()}
+```
+
+Use that form in the admin:
+
+```python
+from django.contrib import admin
+
+
+@admin.register(Service)
+class ServiceAdmin(admin.ModelAdmin):
+    form = ServiceForm
+```
+
+Or use the widget for every `JSONField` in a model admin:
+
+```python
+from django.db import models
+
+
+class ServiceAdmin(admin.ModelAdmin):
+    formfield_overrides = {models.JSONField: {"widget": ListWidget}}
+```
+
+Each value gets its own `<input type="text">` with a remove button, and there's an "Add item" button at the end.
+
+### Options
+
+Set them as constructor kwargs, or as class attributes on a subclass. Kwargs win over class attributes.
+
+| Option | Default | What it does |
+|--------|---------|--------------|
+| `mode` | `"text"` | Shortcut for `value_type`. Built in: `"text"` (string) and `"digits"` (number). |
+| `value_type` | from `mode` | `"string"` or `"number"`. A hint for your backend code only, read it as `widget.value_type`. It doesn't change rendering or what the browser submits. |
+| `input_attrs` | `{}` | Extra attributes set on every value input, e.g. `{"maxLength": 5, "placeholder": "Port"}`. |
+| `min_items` | `0` | How many inputs are always on screen. Remove buttons hide when this count is reached. |
+| `layout` | `"block"` | `"block"`: one item per row. `"inline"`: items wrap left to right, good for a table cell. |
+| `add_label` | `"Add item"` | Accessible name (`title` and `aria-label`) of the add button. |
+| `add_text` | `"Add item"` | Visible text of the add button. `""` shows only the icon. |
+| `remove_label` | `"Remove item"` | Accessible name of each remove button. |
+
+Standard widget `attrs` work too. A `class` or `style` you pass is added to the hidden textarea next to the widget's own.
+
+`input_attrs` keys are set as DOM properties, not HTML attributes. Use the JS names: `maxLength`, `readOnly`, `inputMode`, not `maxlength`, `readonly`, `inputmode`.
+
+### Reusable subclasses
+
+When the same setup is used in several places, put it in a subclass:
+
+```python
+class PortsWidget(ListWidget):
+    mode = "digits"
+    layout = "inline"
+    min_items = 1
+    input_attrs = {"maxLength": 5}
+    add_label = "Add port"
+    add_text = ""
+    remove_label = "Remove port"
+```
+
+### Values are always strings
+
+Whatever the mode, the browser submits a JSON array of strings. Each value is trimmed and empty inputs are dropped. So `[" 80", "", "443 "]` on screen becomes `["80", "443"]`.
+
+Converting and checking values is your form's job. `mode` and `value_type` only tell your code what to expect:
+
+```python
+class ServiceForm(forms.ModelForm):
+    class Meta:
+        model = Service
+        fields = "__all__"
+        widgets = {"ports": PortsWidget()}
+
+    def clean_ports(self):
+        cleaned = []
+        for item in self.cleaned_data.get("ports") or []:
+            try:
+                port = int(item)
+            except (TypeError, ValueError):
+                raise forms.ValidationError(f"'{item}' is not a valid port number.")
+            if not 1 <= port <= 65535:
+                raise forms.ValidationError(f"Port {port} must be between 1 and 65535.")
+            cleaned.append(port)
+        return cleaned
+```
+
+The inputs never limit what the user can type. If you want a limit in the browser, add it yourself through `input_attrs`.
+
+### Custom modes
+
+Add a mode with a `MODES` dict on a subclass:
+
+```python
+class MyListWidget(ListWidget):
+    MODES = {
+        **ListWidget.MODES,
+        "decimal": {"value_type": "decimal"},
+    }
+
+
+MyListWidget(mode="decimal").value_type  # "decimal"
+```
+
+An unknown mode falls back to `value_type="string"`.
+
+### Inline formsets
+
+Widgets in rows added with the admin's "Add another" button work too. The script listens for Django's `formset:added` event and skips the hidden `__prefix__` template row.
+
+If you add rows with your own JS, dispatch the same event from the new row, so the widget gets set up:
+
+```js
+row.dispatchEvent(new CustomEvent("formset:added", { bubbles: true }));
+```
+
+## Styling
+
+The bundled CSS (`jsonsson/css/list.css`) only does layout: spacing, the remove cross inside the input, hiding remove buttons at `min_items`. It looks native in the Django admin because it uses the admin's `admin/img/icon-addlink.svg` icon and `--border-color` variable. Outside the admin it still works. The add button just has no icon, and the hover color falls back to `#ccc`.
+
+Sizing is up to you. Add your own CSS through the widget's `Media`:
+
+```python
+class PortsWidget(ListWidget):
+    class Media:
+        css = {"all": ("myapp/css/ports.css",)}
+```
+
+```css
+.jsonsson-list .jsonsson-list-value {
+    width: 5ch;
+    box-sizing: content-box;
+}
+```
+
+Django merges a subclass's `Media` with its parent's, so the bundled JS and CSS are still included.
+
+### CSS classes
+
+| Class | Element |
+|-------|---------|
+| `jsonsson-list` | Outer container |
+| `jsonsson-list--block` | Outer container, when `layout="block"` |
+| `jsonsson-list-source` | The hidden textarea with the real value |
+| `jsonsson-list-items` | Wrapper around items and the add button |
+| `jsonsson-list-items--at-min` | Same wrapper, when the item count is at `min_items` |
+| `jsonsson-list-item` | One item (input plus remove button) |
+| `jsonsson-list-value` | The input of one item |
+| `jsonsson-list-remove` | Remove button of one item |
+| `jsonsson-list-add` | Add button |
+| `jsonsson-list-add--icon-only` | Add button, when `add_text=""` |
+
+### Custom markup
+
+The HTML comes from the `jsonsson/widgets/list.html` template. Override it in your project's templates to change it. Keep the CSS classes and `data-*` attributes, the script depends on them.
+
+With Django's default form renderer, templates are looked up in installed apps, so put the override in an app listed before `jsonsson` in `INSTALLED_APPS`. To use project-level `TEMPLATES` dirs, set `FORM_RENDERER = "django.forms.renderers.TemplatesSetting"`.
+
+The template gets the usual widget context, plus `widget.jsonsson`:
+
+| Key | Value |
+|-----|-------|
+| `block` | `True` when `layout="block"` |
+| `min_items` | `min_items` as an int |
+| `input_attrs` | `input_attrs` as a JSON string |
+| `add_label`, `add_text`, `remove_label` | The labels |
+
+## Limitations
+
+- The field value must be a JSON array. `null` or an object breaks the script. For a model field, use `default=list`, and avoid `null=True` or make sure the value is never `None`.
+- Only flat lists of scalar values. Nested lists and objects aren't supported yet.
+- Values come back as strings (see above).
+- Needs JavaScript. Without it the user sees nothing, since the textarea is hidden.
+
+## Development
+
+Uses [uv](https://docs.astral.sh/uv/).
+
+```bash
+make install-dev   # install all dependencies
+make test          # run tests
+make fmt           # format with black
+make lint          # check formatting (CI)
+make build         # build sdist and wheel into dist/
+```
+
+CI runs `black --check` and the tests on Python 3.10 / Django 4.2, Python 3.12 / Django 5.2 and Python 3.14 / Django 6.0.