django-form-matrix 0.1.0__py3-none-any.whl

django_form_matrix/__init__.py

@@ -0,0 +1,6 @@
+from django_form_matrix.fields import Column, MatrixField, Row
+from django_form_matrix.widgets import MatrixWidget
+
+__version__ = "0.1.0"
+
+__all__ = ["Column", "MatrixField", "MatrixWidget", "Row", "__version__"]

django_form_matrix/apps.py

@@ -0,0 +1,7 @@
+from django.apps import AppConfig
+
+
+class DjangoFormMatrixConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "django_form_matrix"
+    label = "django_form_matrix"

django_form_matrix/contrib/permissions.py

@@ -0,0 +1,177 @@
+"""
+Permissions in a matrix: one collapsible section per app, one row per model and
+a column per basic action (add, view, change, delete), with the other
+permissions of the model at the end of its row. Django stores the name of each
+permission ("Can add invoice") in English when creating it; here they are shown
+translated.
+
+It needs ``django.contrib.auth``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+from django import forms
+from django.utils.text import capfirst
+from django.utils.translation import gettext, pgettext_lazy
+from django.utils.translation import gettext_lazy as _
+
+if TYPE_CHECKING:
+    from django.contrib.auth.models import Permission
+    from django.db.models import QuerySet
+
+ACTIONS = {
+    "add": _("Can add %(model)s"),
+    "change": _("Can change %(model)s"),
+    "delete": _("Can delete %(model)s"),
+    "view": _("Can view %(model)s"),
+}
+# Columns of the matrix, in the order they are shown.
+ACTION_COLUMNS = (
+    ("add", pgettext_lazy("permission", "Add")),
+    ("view", pgettext_lazy("permission", "View")),
+    ("change", pgettext_lazy("permission", "Change")),
+    ("delete", pgettext_lazy("permission", "Delete")),
+)
+
+
+@dataclass(frozen=True)
+class PermissionParts:
+    """Where a permission belongs and what it allows, translated."""
+
+    app: str
+    model: str
+    action: str | None  # "add", "change"... for the basic ones
+    name: str
+
+
+def permission_parts(permission: Permission) -> PermissionParts:
+    content_type = permission.content_type
+    model = content_type.model_class()
+    if model is None:  # permission of a removed model
+        return PermissionParts(
+            content_type.app_label, content_type.model, None, permission.name
+        )
+    opts = model._meta
+    action, _separator, model_name = permission.codename.partition("_")
+    if action in ACTIONS and model_name == opts.model_name:
+        return PermissionParts(
+            str(capfirst(opts.app_config.verbose_name)),
+            str(capfirst(opts.verbose_name)),
+            action,
+            ACTIONS[action] % {"model": opts.verbose_name},
+        )
+    return PermissionParts(
+        str(capfirst(opts.app_config.verbose_name)),
+        str(capfirst(opts.verbose_name)),
+        None,
+        gettext(permission.name),
+    )
+
+
+def permission_label(permission: Permission) -> str:
+    """ "App | Model | Can add model", translated like the rest of the admin."""
+    if permission.content_type.model_class() is None:
+        return str(permission)
+    parts = permission_parts(permission)
+    return f"{parts.app} | {parts.model} | {parts.name}"
+
+
+@dataclass
+class PermissionRow:
+    model: str
+    cells: dict[str, dict[str, Any]] = field(default_factory=dict)
+    others: list[dict[str, Any]] = field(default_factory=list)
+
+    @property
+    def columns(self) -> list[tuple[str, dict[str, Any] | None]]:
+        return [(action, self.cells.get(action)) for action, _label in ACTION_COLUMNS]
+
+
+@dataclass
+class PermissionApp:
+    name: str
+    rows: dict[str, PermissionRow] = field(default_factory=dict)
+
+    @property
+    def options(self) -> list[dict[str, Any]]:
+        return [
+            option
+            for row in self.rows.values()
+            for option in [*row.cells.values(), *row.others]
+        ]
+
+    @property
+    def has_others(self) -> bool:
+        return any(row.others for row in self.rows.values())
+
+    @property
+    def checked(self) -> int:
+        return sum(option["checked"] for option in self.options)
+
+    @property
+    def total(self) -> int:
+        return len(self.options)
+
+
+class PermissionMatrixWidget(forms.CheckboxSelectMultiple):
+    """
+    Permissions as a matrix (see the module docstring). It submits like a
+    CheckboxSelectMultiple, so validation and saving do not change; only the
+    permissions of the queryset of the field are shown.
+    """
+
+    template_name = "django_form_matrix/permissions.html"
+
+    class Media:
+        css = {"all": ("django_form_matrix/css/matrix.css",)}
+        js = ("django_form_matrix/js/matrix.js",)
+
+    def get_context(self, name: str, value: Any, attrs: Any) -> dict[str, Any]:
+        context = super().get_context(name, value, attrs)
+        selected = {str(item) for item in value or []}
+        apps: dict[str, PermissionApp] = {}
+        # Choices of a ModelMultipleChoiceField: no empty one, and each value
+        # carries its permission.
+        for choice, _label in self.choices:
+            permission = choice.instance  # type: ignore[union-attr]
+            parts = permission_parts(permission)
+            row = apps.setdefault(parts.app, PermissionApp(parts.app)).rows.setdefault(
+                parts.model, PermissionRow(parts.model)
+            )
+            option = {
+                "value": permission.pk,
+                "id": f"{context['widget']['attrs'].get('id', name)}_{permission.pk}",
+                "label": parts.name,
+                "checked": str(permission.pk) in selected,
+            }
+            if parts.action:
+                row.cells[parts.action] = option
+            else:
+                row.others.append(option)
+        context["widget"].update(
+            {
+                "apps": [
+                    PermissionApp(app.name, dict(sorted(app.rows.items())))
+                    for app in sorted(apps.values(), key=lambda app: app.name)
+                ],
+                "columns": ACTION_COLUMNS,
+                "disabled": bool(context["widget"]["attrs"].get("disabled")),
+            }
+        )
+        return context
+
+
+class PermissionMultipleChoiceField(forms.ModelMultipleChoiceField):
+    """Permissions labelled with their translated names, chosen in a matrix."""
+
+    widget = PermissionMatrixWidget
+
+    def __init__(self, queryset: QuerySet[Permission], **kwargs: Any) -> None:
+        kwargs["widget"] = PermissionMatrixWidget
+        super().__init__(queryset.select_related("content_type"), **kwargs)
+
+    def label_from_instance(self, obj: Any) -> str:
+        return permission_label(obj)

django_form_matrix/contrib/unfold.py

@@ -0,0 +1,23 @@
+"""django-unfold integration."""
+
+from django.forms import Media
+
+
+class UnfoldMatrixMixin:
+    """
+    Puts the matrix on Unfold's palette (light and dark)::
+
+        from unfold.admin import ModelAdmin
+
+        class PlanAdmin(UnfoldMatrixMixin, ModelAdmin):
+            form = PlanForm
+    """
+
+    @property
+    def media(self) -> Media:
+        return super().media + Media(  # type: ignore[misc]
+            css={"all": ("django_form_matrix/css/unfold.css",)},
+        )
+
+
+__all__ = ["UnfoldMatrixMixin"]

django_form_matrix/fields.py

@@ -0,0 +1,159 @@
+"""
+A form field to fill a table: one row per item, one column per property and,
+in every cell, a form field of its own (a checkbox, a number, a choice...).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+from django import forms
+from django.core.exceptions import ValidationError
+from django.utils.translation import gettext_lazy as _
+
+from django_form_matrix.widgets import MatrixWidget
+
+if TYPE_CHECKING:
+    from collections.abc import Collection, Iterable, Mapping
+
+
+def _boolean() -> forms.Field:
+    return forms.BooleanField(required=False)
+
+
+@dataclass(frozen=True)
+class Column:
+    """
+    A column and the form field that is in each of its cells (a checkbox
+    unless said otherwise). Checkbox columns get a shortcut to check them all.
+    """
+
+    key: str
+    label: Any
+    field: forms.Field = field(default_factory=_boolean)
+
+    @property
+    def is_checkbox(self) -> bool:
+        return isinstance(self.field.widget, forms.CheckboxInput)
+
+
+@dataclass(frozen=True)
+class Row:
+    """
+    A row, optionally inside a collapsible ``section``. ``columns`` are the keys
+    of the columns that have a cell in this row (all of them if it is None).
+    """
+
+    key: str
+    label: Any
+    section: Any = None
+    columns: Collection[str] | None = None
+
+    def __post_init__(self) -> None:
+        if self.columns is not None:
+            object.__setattr__(self, "columns", frozenset(self.columns))
+
+    def has(self, column: str) -> bool:
+        return self.columns is None or column in self.columns
+
+
+class MatrixField(forms.Field):
+    """
+    Its value is ``{row key: {column key: cleaned value of the cell}}``, with
+    only the cells that exist. Each cell is cleaned by the field of its column,
+    so its validation and its widget are the ones of Django; a cell that fails
+    reports its row and column. It is not required by default; when it is, at
+    least one cell must have a value.
+    """
+
+    widget = MatrixWidget
+    default_error_messages = {
+        "cell": _("%(row)s, %(column)s: %(error)s"),
+    }
+
+    def __init__(
+        self,
+        *,
+        rows: Iterable[Row],
+        columns: Iterable[Column],
+        required: bool = False,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(required=required, **kwargs)
+        self.rows = rows
+        self.columns = columns
+
+    @property
+    def rows(self) -> tuple[Row, ...]:
+        return self._rows
+
+    @rows.setter
+    def rows(self, rows: Iterable[Row]) -> None:
+        rows = tuple(rows)
+        self._check_unique("row", [row.key for row in rows])
+        self._rows = rows
+        self.widget.rows = rows
+
+    @property
+    def columns(self) -> tuple[Column, ...]:
+        return self._columns
+
+    @columns.setter
+    def columns(self, columns: Iterable[Column]) -> None:
+        columns = tuple(columns)
+        self._check_unique("column", [column.key for column in columns])
+        self._columns = columns
+        self.widget.columns = columns
+
+    @staticmethod
+    def _check_unique(kind: str, keys: list[str]) -> None:
+        if len(set(keys)) != len(keys):
+            raise ValueError(f"The keys of the {kind}s of a matrix must be unique.")
+
+    def clean(self, value: Mapping[str, Mapping[str, Any]] | None) -> dict[str, Any]:
+        value = value or {}
+        cleaned: dict[str, dict[str, Any]] = {}
+        errors: list[ValidationError] = []
+        for row in self.rows:
+            cells = cleaned[row.key] = {}
+            for column in self.columns:
+                if not row.has(column.key):
+                    continue
+                raw = value.get(row.key, {}).get(column.key)
+                try:
+                    cells[column.key] = column.field.clean(raw)
+                except ValidationError as error:
+                    errors.extend(
+                        ValidationError(
+                            self.error_messages["cell"],
+                            code="cell",
+                            params={
+                                "row": row.label,
+                                "column": column.label,
+                                "error": message,
+                            },
+                        )
+                        for message in error.messages
+                    )
+        if errors:
+            raise ValidationError(errors)
+        if self.required and not any(
+            cell for cells in cleaned.values() for cell in cells.values()
+        ):
+            raise ValidationError(self.error_messages["required"], code="required")
+        self.run_validators(cleaned)
+        return cleaned
+
+    def has_changed(self, initial: Any, data: Any) -> bool:
+        initial = initial or {}
+        data = data or {}
+        return any(
+            column.field.has_changed(
+                initial.get(row.key, {}).get(column.key),
+                data.get(row.key, {}).get(column.key),
+            )
+            for row in self.rows
+            for column in self.columns
+            if row.has(column.key)
+        )

django_form_matrix/locale/es/LC_MESSAGES/django.po

@@ -0,0 +1,73 @@
+# Spanish translation of django-form-matrix.
+#
+msgid ""
+msgstr ""
+"Project-Id-Version: django-form-matrix 0.1.0\n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-10-16 18:04-0500\n"
+"PO-Revision-Date: 2026-10-17 01:00+0200\n"
+"Last-Translator: Rodolfo Becerra\n"
+"Language-Team: Spanish\n"
+"Language: es\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Plural-Forms: nplurals=3; plural=n == 1 ? 0 : n != 0 && n % 1000000 == 0 ? 1 : 2;\n"
+
+#: contrib/permissions.py
+#, python-format
+msgid "Can add %(model)s"
+msgstr "Puede añadir %(model)s"
+
+#: contrib/permissions.py
+#, python-format
+msgid "Can change %(model)s"
+msgstr "Puede modificar %(model)s"
+
+#: contrib/permissions.py
+#, python-format
+msgid "Can delete %(model)s"
+msgstr "Puede eliminar %(model)s"
+
+#: contrib/permissions.py
+#, python-format
+msgid "Can view %(model)s"
+msgstr "Puede ver %(model)s"
+
+#: contrib/permissions.py
+msgctxt "permission"
+msgid "Add"
+msgstr "Añadir"
+
+#: contrib/permissions.py
+msgctxt "permission"
+msgid "View"
+msgstr "Ver"
+
+#: contrib/permissions.py
+msgctxt "permission"
+msgid "Change"
+msgstr "Modificar"
+
+#: contrib/permissions.py
+msgctxt "permission"
+msgid "Delete"
+msgstr "Eliminar"
+
+#: fields.py
+#, python-format
+msgid "%(row)s, %(column)s: %(error)s"
+msgstr "%(row)s, %(column)s: %(error)s"
+
+#: templates/django_form_matrix/matrix.html
+#: templates/django_form_matrix/permissions.html
+msgid "All"
+msgstr "Todo"
+
+#: templates/django_form_matrix/permissions.html
+msgid "Others"
+msgstr "Otros"
+
+#: templates/django_form_matrix/permissions.html
+msgid "No permissions available."
+msgstr "No hay permisos disponibles."

django_form_matrix/static/django_form_matrix/css/matrix.css

@@ -0,0 +1,145 @@
+/*
+ * Matrix (templates/django_form_matrix). The colours are the ones of the
+ * Django admin when it is there; set the --form-matrix-* variables to use
+ * the matrix anywhere else.
+ */
+.form-matrix {
+    --form-matrix-border: var(--hairline-color, #ccc);
+    --form-matrix-heading-bg: var(--darkened-bg, #f8f8f8);
+    --form-matrix-quiet: var(--body-quiet-color, #666);
+
+    display: flex;
+    flex-direction: column;
+    gap: 6px;
+    width: 100%;
+    max-width: 900px;
+}
+
+.form-matrix-section {
+    border: 1px solid var(--form-matrix-border);
+    border-radius: 4px;
+}
+
+/* Unfold draws its chevron at the end of every summary, absolutely placed. */
+.form-matrix-section > summary {
+    position: relative;
+    display: flex;
+    justify-content: space-between;
+    padding: 6px 36px 6px 10px;
+    cursor: pointer;
+    background: var(--form-matrix-heading-bg);
+    font-weight: bold;
+}
+
+/* Centred (it is 18px high); Unfold turns it when the section is open. */
+.form-matrix-section > summary::after {
+    top: calc(50% - 9px);
+}
+
+.form-matrix-section[open] > summary {
+    margin-bottom: 0;
+}
+
+.form-matrix-count {
+    font-weight: normal;
+    color: var(--form-matrix-quiet);
+}
+
+/* Fixed layout with the same widths in every section: the columns line up. */
+.form-matrix-section table {
+    width: 100%;
+    border-collapse: collapse;
+    table-layout: fixed;
+}
+
+.form-matrix-row-column {
+    width: 26%;
+}
+
+.form-matrix-column {
+    width: 11%;
+}
+
+.form-matrix-section th,
+.form-matrix-section td {
+    padding: 4px 8px;
+    text-align: center;
+    vertical-align: middle;
+}
+
+.form-matrix-section thead th {
+    vertical-align: bottom;
+}
+
+.form-matrix-section input[type="checkbox"] {
+    margin: 0;
+}
+
+.form-matrix-section label {
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+    padding: 0;
+    font-size: inherit;
+    white-space: nowrap;
+}
+
+.form-matrix-section th[scope="row"] label,
+.form-matrix-section thead th:first-child label {
+    white-space: normal;
+}
+
+/* The cells that are not checkboxes take their column. */
+.form-matrix-section td input:not([type="checkbox"]),
+.form-matrix-section td select {
+    box-sizing: border-box;
+    width: 100%;
+    min-width: 0;
+}
+
+/*
+ * The checkbox of a column above its name, over the checkboxes of the column
+ * (on the left for "Others", whose checkboxes are listed from the left).
+ */
+.form-matrix-section thead th:not(:first-child) label {
+    flex-direction: column-reverse;
+    gap: 4px;
+}
+
+.form-matrix-section th[scope="row"],
+.form-matrix-section thead th:first-child,
+.form-matrix-section .form-matrix-others {
+    text-align: left;
+}
+
+.form-matrix-section thead th.form-matrix-others label {
+    align-items: flex-start;
+}
+
+/*
+ * The extra checkboxes of a row, one under the other and wrapping inside
+ * their column, not past the matrix; their checkbox next to their first line.
+ */
+td.form-matrix-others label {
+    display: flex;
+    align-items: flex-start;
+    white-space: normal;
+    text-align: left;
+}
+
+td.form-matrix-others label + label {
+    margin-top: 4px;
+}
+
+td.form-matrix-others input[type="checkbox"] {
+    flex: none;
+    margin-top: 2px;
+}
+
+.form-matrix-missing {
+    color: var(--form-matrix-quiet);
+}
+
+.form-matrix-placeholder {
+    visibility: hidden;
+}

django_form_matrix/static/django_form_matrix/css/unfold.css

@@ -0,0 +1,35 @@
+/*
+ * The colours of the matrix on Unfold's palette (Unfold does not define the
+ * variables of Django's admin). Unfold switches to dark with a "dark" class
+ * on <html>. The selectors are more specific than matrix.css's, so it wins
+ * whatever the order the stylesheets are loaded in.
+ */
+html .form-matrix {
+    --form-matrix-border: var(--color-base-200);
+    --form-matrix-heading-bg: var(--color-base-50);
+    --form-matrix-quiet: var(--color-base-500);
+}
+
+html.dark .form-matrix {
+    --form-matrix-border: var(--color-base-800);
+    --form-matrix-heading-bg: rgb(255 255 255 / 0.02);
+    --form-matrix-quiet: var(--color-base-400);
+}
+
+/* Unfold's inputs are styled by its own widgets; these cells are Django's. */
+html .form-matrix td input:not([type="checkbox"]),
+html .form-matrix td select {
+    padding: 0.375rem 0.625rem;
+    border: 1px solid var(--color-base-200);
+    border-radius: 0.375rem;
+    background: #fff;
+    color: var(--color-base-700);
+    font-size: 0.875rem;
+}
+
+html.dark .form-matrix td input:not([type="checkbox"]),
+html.dark .form-matrix td select {
+    border-color: var(--color-base-700);
+    background: var(--color-base-900);
+    color: var(--color-base-200);
+}

django_form_matrix/static/django_form_matrix/js/matrix.js

@@ -0,0 +1,67 @@
+{
+    // Shortcuts of the matrix (templates/django_form_matrix): the checkbox of a
+    // row, a column or a whole section sets every checkbox it covers, and shows
+    // whether they are all, some or none checked.
+    const CELL = "input[type=checkbox][name]:not([disabled])";
+
+    function covered(toggle) {
+        const table = toggle.closest("table");
+        switch (toggle.dataset.formMatrixToggle) {
+            case "row":
+                return toggle.closest("tr").querySelectorAll(CELL);
+            case "column":
+                return [...table.querySelectorAll("td[data-column]")]
+                    .filter(
+                        (cell) => cell.dataset.column === toggle.dataset.column,
+                    )
+                    .flatMap((cell) => [...cell.querySelectorAll(CELL)]);
+            default:
+                return table.querySelectorAll(CELL);
+        }
+    }
+
+    function refresh(section) {
+        for (const toggle of section.querySelectorAll(
+            "[data-form-matrix-toggle]",
+        )) {
+            const inputs = [...covered(toggle)];
+            const checked = inputs.filter((input) => input.checked).length;
+            toggle.disabled = inputs.length === 0;
+            toggle.checked = inputs.length > 0 && checked === inputs.length;
+            toggle.indeterminate = checked > 0 && checked < inputs.length;
+        }
+        const count = section.querySelector("[data-form-matrix-count]");
+        if (count) {
+            const all = section.querySelectorAll("input[type=checkbox][name]");
+            const checked = [...all].filter((input) => input.checked).length;
+            count.textContent = `${checked}/${all.length}`;
+        }
+    }
+
+    document.addEventListener("change", (event) => {
+        const section = event.target.closest(".form-matrix-section");
+        if (!section) {
+            return;
+        }
+        if (event.target.dataset.formMatrixToggle) {
+            for (const input of covered(event.target)) {
+                input.checked = event.target.checked;
+            }
+        }
+        refresh(section);
+    });
+
+    function init() {
+        for (const section of document.querySelectorAll(
+            ".form-matrix-section",
+        )) {
+            refresh(section);
+        }
+    }
+
+    if (document.readyState === "loading") {
+        document.addEventListener("DOMContentLoaded", init);
+    } else {
+        init();
+    }
+}

django_form_matrix/templates/django_form_matrix/matrix.html

@@ -0,0 +1,78 @@
+{% load i18n %}
+<div class="form-matrix"{% if widget.attrs.id %} id="{{ widget.attrs.id }}"{% endif %}>
+  {% for section in widget.sections %}
+    {% if section.name %}
+      <details class="form-matrix-section"{% if section.is_open %} open{% endif %}>
+        <summary>
+          {% block section_summary %}
+            <span class="form-matrix-section-name">{{ section.name }}</span>
+            {% if section.total %}
+              <span class="form-matrix-count" data-form-matrix-count>{{ section.checked }}/{{ section.total }}</span>
+            {% endif %}
+          {% endblock section_summary %}
+        </summary>
+    {% else %}
+      <div class="form-matrix-section">
+    {% endif %}
+    <table>
+      {# Same column widths in every section, so the columns line up. #}
+      <colgroup>
+        <col class="form-matrix-row-column">
+        {% for column in widget.columns %}<col class="form-matrix-column">{% endfor %}
+      </colgroup>
+      <thead>
+        <tr>
+          <th scope="col">
+            {% block section_toggle %}
+              {% if section.has_checkboxes and not widget.disabled %}
+                <label><input type="checkbox" data-form-matrix-toggle="section"> {% translate "All" %}</label>
+              {% endif %}
+            {% endblock section_toggle %}
+          </th>
+          {% for column in widget.columns %}
+            <th scope="col">
+              {% block column_heading %}
+                {% if column.is_checkbox and not widget.disabled %}
+                  <label><input type="checkbox" data-form-matrix-toggle="column" data-column="{{ forloop.counter0 }}"> {{ column.label }}</label>
+                {% else %}
+                  {{ column.label }}
+                {% endif %}
+              {% endblock column_heading %}
+            </th>
+          {% endfor %}
+        </tr>
+      </thead>
+      <tbody>
+        {% for row in section.rows %}
+          <tr>
+            <th scope="row">
+              {% block row_heading %}
+                {% if row.has_checkboxes and not widget.disabled %}
+                  <label><input type="checkbox" data-form-matrix-toggle="row"> {{ row.label }}</label>
+                {% else %}
+                  {{ row.label }}
+                {% endif %}
+              {% endblock row_heading %}
+            </th>
+            {% for cell in row.cells %}
+              <td data-column="{{ forloop.counter0 }}">
+                {% if cell.html %}
+                  {% block cell %}{{ cell.html }}{% endblock %}
+                {% else %}
+                  {% block missing_cell %}<span class="form-matrix-missing" aria-hidden="true">—</span>{% endblock %}
+                {% endif %}
+              </td>
+            {% endfor %}
+          </tr>
+        {% endfor %}
+      </tbody>
+    </table>
+    {% if section.name %}
+      </details>
+    {% else %}
+      </div>
+    {% endif %}
+  {% empty %}
+    {% block empty %}{% endblock %}
+  {% endfor %}
+</div>

django_form_matrix/templates/django_form_matrix/permissions.html

@@ -0,0 +1,89 @@
+{% load i18n %}
+<div class="form-matrix"{% if widget.attrs.id %} id="{{ widget.attrs.id }}"{% endif %}>
+  {% for app in widget.apps %}
+    <details class="form-matrix-section"{% if app.checked %} open{% endif %}>
+      <summary>
+        {% block section_summary %}
+          <span class="form-matrix-section-name">{{ app.name }}</span>
+          <span class="form-matrix-count" data-form-matrix-count>{{ app.checked }}/{{ app.total }}</span>
+        {% endblock section_summary %}
+      </summary>
+      <table>
+        {# Same column widths in every app, so the columns line up. #}
+        <colgroup>
+          <col class="form-matrix-row-column">
+          {% for action, label in widget.columns %}<col class="form-matrix-column">{% endfor %}
+          <col class="form-matrix-others-column">
+        </colgroup>
+        <thead>
+          <tr>
+            <th scope="col">
+              {% block section_toggle %}
+                {% if not widget.disabled %}
+                  <label><input type="checkbox" data-form-matrix-toggle="section"> {% translate "All" %}</label>
+                {% endif %}
+              {% endblock section_toggle %}
+            </th>
+            {% for action, label in widget.columns %}
+              <th scope="col">
+                {% block column_heading %}
+                  {% if widget.disabled %}{{ label }}{% else %}
+                    <label><input type="checkbox" data-form-matrix-toggle="column" data-column="{{ action }}"> {{ label }}</label>
+                  {% endif %}
+                {% endblock column_heading %}
+              </th>
+            {% endfor %}
+            <th scope="col" class="form-matrix-others">
+              {% block others_heading %}
+                {% if widget.disabled %}{% translate "Others" %}{% else %}
+                  <label>
+                    {% if app.has_others %}
+                      <input type="checkbox" data-form-matrix-toggle="column" data-column="others">
+                    {% else %}
+                      {# Room of the checkbox, so the heading lines up with the others. #}
+                      <input type="checkbox" class="form-matrix-placeholder" tabindex="-1" aria-hidden="true" disabled>
+                    {% endif %}
+                    {% translate "Others" %}
+                  </label>
+                {% endif %}
+              {% endblock others_heading %}
+            </th>
+          </tr>
+        </thead>
+        <tbody>
+          {% for row in app.rows.values %}
+            <tr>
+              <th scope="row">
+                {% block row_heading %}
+                  {% if widget.disabled %}{{ row.model }}{% else %}
+                    <label><input type="checkbox" data-form-matrix-toggle="row"> {{ row.model }}</label>
+                  {% endif %}
+                {% endblock row_heading %}
+              </th>
+              {% for action, option in row.columns %}
+                <td data-column="{{ action }}">
+                  {% if option %}
+                    {% block permission %}
+                      <input type="checkbox" name="{{ widget.name }}" value="{{ option.value }}" id="{{ option.id }}" title="{{ option.label }}" aria-label="{{ row.model }}: {{ option.label }}"{% if option.checked %} checked{% endif %}{% if widget.disabled %} disabled{% endif %}>
+                    {% endblock permission %}
+                  {% else %}
+                    {% block missing_cell %}<span class="form-matrix-missing" aria-hidden="true">—</span>{% endblock %}
+                  {% endif %}
+                </td>
+              {% endfor %}
+              <td class="form-matrix-others" data-column="others">
+                {% for option in row.others %}
+                  {% block other_permission %}
+                    <label><input type="checkbox" name="{{ widget.name }}" value="{{ option.value }}" id="{{ option.id }}"{% if option.checked %} checked{% endif %}{% if widget.disabled %} disabled{% endif %}> {{ option.label }}</label>
+                  {% endblock other_permission %}
+                {% endfor %}
+              </td>
+            </tr>
+          {% endfor %}
+        </tbody>
+      </table>
+    </details>
+  {% empty %}
+    {% block empty %}<p>{% translate "No permissions available." %}</p>{% endblock %}
+  {% endfor %}
+</div>

django_form_matrix/widgets.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+from django import forms
+
+if TYPE_CHECKING:
+    from django_form_matrix.fields import Column, Row
+
+
+@dataclass
+class Section:
+    """The rows under one heading; the ones without section go together."""
+
+    name: Any
+    rows: list[dict[str, Any]] = field(default_factory=list)
+
+    @property
+    def checkboxes(self) -> list[dict[str, Any]]:
+        return [
+            cell
+            for row in self.rows
+            for cell in row["cells"]
+            if cell["checkbox"] and cell["html"]
+        ]
+
+    @property
+    def has_checkboxes(self) -> bool:
+        return bool(self.checkboxes)
+
+    @property
+    def checked(self) -> int:
+        return sum(cell["checked"] for cell in self.checkboxes)
+
+    @property
+    def total(self) -> int:
+        return len(self.checkboxes)
+
+    @property
+    def is_open(self) -> bool:
+        # Open when something in it is filled (also when it fails), and when
+        # it has no checkboxes to count.
+        return not self.total or any(
+            cell["filled"] for row in self.rows for cell in row["cells"]
+        )
+
+
+class MatrixWidget(forms.Widget):
+    """
+    A table with the widget of each column in every cell. Every cell is
+    submitted on its own, as ``<name>__<row key>__<column key>``, so it reads
+    like any other widget; the value is ``{row key: {column key: raw value}}``.
+    """
+
+    template_name = "django_form_matrix/matrix.html"
+
+    class Media:
+        css = {"all": ("django_form_matrix/css/matrix.css",)}
+        js = ("django_form_matrix/js/matrix.js",)
+
+    def __init__(
+        self,
+        attrs: dict[str, Any] | None = None,
+        rows: tuple[Row, ...] = (),
+        columns: tuple[Column, ...] = (),
+    ) -> None:
+        super().__init__(attrs)
+        self.rows = rows
+        self.columns = columns
+
+    @staticmethod
+    def cell_name(name: str, row: Row, column: Column) -> str:
+        return f"{name}__{row.key}__{column.key}"
+
+    def value_from_datadict(
+        self, data: Any, files: Any, name: str
+    ) -> dict[str, dict[str, Any]]:
+        return {
+            row.key: {
+                column.key: column.field.widget.value_from_datadict(
+                    data, files, self.cell_name(name, row, column)
+                )
+                for column in self.columns
+                if row.has(column.key)
+            }
+            for row in self.rows
+        }
+
+    def value_omitted_from_data(self, data: Any, files: Any, name: str) -> bool:
+        return all(
+            column.field.widget.value_omitted_from_data(
+                data, files, self.cell_name(name, row, column)
+            )
+            for row in self.rows
+            for column in self.columns
+            if row.has(column.key)
+        )
+
+    def format_value(self, value: Any) -> Any:
+        return value
+
+    def get_context(self, name: str, value: Any, attrs: Any) -> dict[str, Any]:
+        context = super().get_context(name, value, attrs)
+        widget = context["widget"]
+        value = value or {}
+        base_id = widget["attrs"].get("id") or f"id_{name}"
+        disabled = bool(widget["attrs"].get("disabled"))
+        sections: dict[Any, Section] = {}
+        for i, row in enumerate(self.rows):
+            cells = []
+            for j, column in enumerate(self.columns):
+                cell: dict[str, Any] = {
+                    "column": column,
+                    "html": None,
+                    "checkbox": column.is_checkbox,
+                    "checked": False,
+                    "filled": False,
+                }
+                if row.has(column.key):
+                    cell_value = value.get(row.key, {}).get(column.key)
+                    cell_attrs: dict[str, Any] = {
+                        "id": f"{base_id}_{i}_{j}",
+                        "aria-label": f"{row.label}: {column.label}",
+                    }
+                    if disabled:
+                        cell_attrs["disabled"] = True
+                    cell["html"] = column.field.widget.render(
+                        self.cell_name(name, row, column),
+                        column.field.prepare_value(cell_value),
+                        cell_attrs,
+                    )
+                    cell["filled"] = bool(cell_value)
+                    cell["checked"] = column.is_checkbox and cell["filled"]
+                cells.append(cell)
+            sections.setdefault(row.section, Section(row.section)).rows.append(
+                {
+                    "label": row.label,
+                    "cells": cells,
+                    "has_checkboxes": any(c["checkbox"] and c["html"] for c in cells),
+                }
+            )
+        widget.update(
+            sections=list(sections.values()),
+            columns=self.columns,
+            disabled=disabled,
+        )
+        return context

django_form_matrix-0.1.0.dist-info/METADATA

@@ -0,0 +1,217 @@
+Metadata-Version: 2.5
+Name: django-form-matrix
+Version: 0.1.0
+Summary: A form field to fill a table of rows and columns, with a form field in every cell (checkboxes, numbers, choices...), plus a ready-made permission matrix.
+Project-URL: Homepage, https://github.com/rodolvbg/django-form-matrix
+Project-URL: Issues, https://github.com/rodolvbg/django-form-matrix/issues
+Project-URL: Repository, https://github.com/rodolvbg/django-form-matrix
+Author-email: Rodolfo Valentín Becerra García <rodolvbg@gmail.com>
+Maintainer-email: Rodolfo Valentín Becerra García <rodolvbg@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: admin,checkbox,django,form,grid,matrix,permissions,widget
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 5.1
+Classifier: Framework :: Django :: 5.2
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: django>=4.2
+Provides-Extra: dev
+Requires-Dist: coverage[toml]>=7.4; extra == 'dev'
+Requires-Dist: django-stubs[compatible-mypy]>=5; extra == 'dev'
+Requires-Dist: django-unfold>=0.60; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pre-commit>=4; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest-django>=4.8; extra == 'dev'
+Requires-Dist: pytest-playwright>=0.5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: tox-uv>=1; extra == 'dev'
+Requires-Dist: tox>=4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# django-form-matrix
+
+[![Build status](https://github.com/rodolvbg/django-form-matrix/actions/workflows/pytest.yml/badge.svg)](https://github.com/rodolvbg/django-form-matrix/actions/workflows/pytest.yml)
+[![PyPI version](https://img.shields.io/pypi/v/django-form-matrix.svg)](https://pypi.org/project/django-form-matrix/)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/django-form-matrix)](https://pypi.org/project/django-form-matrix/)
+[![PyPI - Django Version](https://img.shields.io/pypi/djversions/django-form-matrix)](https://pypi.org/project/django-form-matrix/)
+[![Downloads](https://static.pepy.tech/personalized-badge/django-form-matrix?period=month&units=international_system&left_color=black&right_color=blue&left_text=Downloads/month)](https://pepy.tech/project/django-form-matrix)
+
+A Django form field to fill a **table**: one row per item, one column per property and, in every cell, a form field of its own — a checkbox, a number, a choice, text. Rows can be grouped in collapsible sections, and checkbox columns get shortcuts to check a row, a column or a whole section.
+
+It works in any Django form and in the admin. A ready-made **permission matrix** (apps → models → add/view/change/delete) is included as a use case.
+
+![A matrix with checkboxes, numbers and choices in its cells, in two sections](https://raw.githubusercontent.com/rodolvbg/django-form-matrix/HEAD/docs/screenshots/hero.png)
+
+## Installation
+
+```bash
+pip install django-form-matrix
+```
+
+Add `django_form_matrix` to `INSTALLED_APPS` (it ships a template, a script and a stylesheet):
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "django_form_matrix",
+]
+```
+
+## Quick start
+
+```python
+from django import forms
+from django_form_matrix import Column, MatrixField, Row
+
+
+class PlanForm(forms.Form):
+    features = MatrixField(
+        rows=[
+            Row("invoices", "Invoices", section="Billing"),
+            Row("quotes", "Quotes", section="Billing"),
+            Row("exports", "Exports", section="Analytics", columns=["enabled"]),
+        ],
+        columns=[
+            Column("enabled", "Enabled"),  # a checkbox unless said otherwise
+            Column(
+                "limit",
+                "Monthly limit",
+                forms.IntegerField(min_value=0, required=False),
+            ),
+        ],
+    )
+```
+
+Render the form as usual and add `{{ form.media }}` (the admin does it for you). The cleaned value has one entry per row with the cells that exist:
+
+```python
+form.cleaned_data["features"]
+# {"invoices": {"enabled": True, "limit": 50},
+#  "quotes": {"enabled": False, "limit": None},
+#  "exports": {"enabled": False}}
+```
+
+That is what a `JSONField` stores, so a `ModelForm` can save it directly.
+
+### Rows and columns
+
+- `Column(key, label, field=BooleanField(required=False))`: the form field of the column. Its validation and its widget are Django's own, and a failing cell is reported with its row and column ("Invoices, Monthly limit: …").
+- `Row(key, label, section=None, columns=None)`: `section` groups rows under a collapsible heading (rows without one go in a plain table); `columns` are the keys of the columns that have a cell in this row, the rest show a dash.
+- `MatrixField(rows=…, columns=…)` is not required by default; with `required=True` at least one cell needs a value. `rows` and `columns` can be reassigned in a form's `__init__` to build the matrix dynamically.
+
+Each cell is submitted as `<name>__<row key>__<column key>`, so it reads like any other widget.
+
+### Shortcuts
+
+Checkbox columns get a checkbox in their heading, every row with checkboxes gets one at its start, and each section gets an "All". They show whether their cells are all, some or none checked, and the heading of a section counts the checked ones. A section opens by itself when something in it is filled.
+
+## Permissions
+
+```python
+from django_form_matrix.contrib.permissions import PermissionMultipleChoiceField
+
+
+class RoleAdmin(admin.ModelAdmin):
+    def formfield_for_manytomany(self, db_field, request, **kwargs):
+        if db_field.name == "permissions":
+            kwargs["form_class"] = PermissionMultipleChoiceField
+        return super().formfield_for_manytomany(db_field, request, **kwargs)
+```
+
+![The permission matrix in the admin](https://raw.githubusercontent.com/rodolvbg/django-form-matrix/HEAD/docs/screenshots/permissions.png)
+
+One section per app, one row per model and a column per action; the other permissions of a model go in an "Others" column. It submits like a `CheckboxSelectMultiple`, so validation and saving do not change, and the names of the permissions are shown translated. Needs `django.contrib.auth`. [docs/examples/permissions.md](https://github.com/rodolvbg/django-form-matrix/blob/HEAD/docs/examples/permissions.md) shows how to build the same matrix by hand with `MatrixField`, with rows that come from the database, for when you need more control.
+
+## Customizing the HTML
+
+Both templates are split in blocks, so a template of yours can extend one and change only a piece, without copying the rest:
+
+```django
+{% extends "django_form_matrix/matrix.html" %}
+{% block section_summary %}<strong>{{ section.name }}</strong>{% endblock %}
+{% block cell %}<div class="my-cell">{{ cell.html }}</div>{% endblock %}
+```
+
+Point a widget to it with `template_name`:
+
+```python
+class MyMatrixWidget(MatrixWidget):
+    template_name = "myapp/my_matrix.html"
+```
+
+| Block | `matrix.html` | `permissions.html` | What it is |
+| --- | --- | --- | --- |
+| `section_summary` | ✓ | ✓ | The heading of a section (its name and count) |
+| `section_toggle` | ✓ | ✓ | The "All" checkbox of a section |
+| `column_heading` | ✓ | ✓ | The heading of a column |
+| `others_heading` | | ✓ | The heading of the "Others" column |
+| `row_heading` | ✓ | ✓ | The heading of a row |
+| `cell` | ✓ | | The widget of a cell (`{{ cell.html }}`) |
+| `permission` | | ✓ | The checkbox of a permission |
+| `other_permission` | | ✓ | A permission of the "Others" column |
+| `missing_cell` | ✓ | ✓ | A cell a row does not have |
+| `empty` | ✓ | ✓ | What shows when there is nothing to fill |
+
+`{{ block.super }}` keeps the original of a block. The classes (`.form-matrix-*`) and the `data-form-matrix-*` attributes are what the stylesheet and the script look for: keep them in your blocks and the shortcuts keep working.
+
+Django looks for the widget templates of a form in the `templates/` of the installed apps, **not** in the `DIRS` of your project. To override `django_form_matrix/matrix.html` itself by name from the project's templates, set `FORM_RENDERER = "django.forms.renderers.TemplatesSetting"`, or put the template in an app listed before `django_form_matrix` in `INSTALLED_APPS`. Extending it with your own `template_name`, as above, needs neither.
+
+## Styling
+
+The stylesheet uses the colours of the Django admin when it is there. Anywhere else, set `--form-matrix-border`, `--form-matrix-heading-bg` and `--form-matrix-quiet` on `.form-matrix`.
+
+### Unfold
+
+[django-unfold](https://github.com/unfoldadmin/django-unfold) does not define the variables of Django's admin, so add `UnfoldMatrixMixin` to the admin: it puts the matrix on Unfold's palette, light and dark, and styles the number, text and select cells like Unfold's own inputs.
+
+```python
+from unfold.admin import ModelAdmin
+from django_form_matrix.contrib.unfold import UnfoldMatrixMixin
+
+
+@admin.register(Plan)
+class PlanAdmin(UnfoldMatrixMixin, ModelAdmin):
+    form = PlanForm
+```
+
+![The matrix in Unfold](https://raw.githubusercontent.com/rodolvbg/django-form-matrix/HEAD/docs/screenshots/unfold.png)
+
+The permission matrix, the use case this library started from, in Unfold:
+
+![The permission matrix in Unfold](https://raw.githubusercontent.com/rodolvbg/django-form-matrix/HEAD/docs/screenshots/unfold-permissions.png)
+
+And in Unfold's dark mode:
+
+![The matrix in Unfold, dark](https://raw.githubusercontent.com/rodolvbg/django-form-matrix/HEAD/docs/screenshots/unfold-dark.png)
+
+## Translations
+
+Ships a Spanish (`es`) translation: the matrix's headings ("Add", "View",
+"Change", "Delete", "Others"), the permissions' names ("Can view plan") and
+its messages follow the active language, like the rest of the admin.
+
+## Development
+
+```bash
+uv sync && npm install
+uv run pytest            # Python + end-to-end (needs `uv run playwright install chromium`)
+npm test                 # JS
+cd example && uv run python manage.py runserver   # demo: Plans and Roles in the admin
+DJANGO_SETTINGS_MODULE=example.settings_unfold uv run python manage.py runserver   # the same, in Unfold
+```

django_form_matrix-0.1.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+django_form_matrix/__init__.py,sha256=sqTm713ZUXTiw-iL3DvySAmREpr9EbCszk3pM4WFmYs,213
+django_form_matrix/apps.py,sha256=36hiEwMuMP_WzHQxw-m_FLT-Nyybfk7PmwQWsbZVfZk,199
+django_form_matrix/fields.py,sha256=w1t6YHAHeu1QK6jUg88WaauGtADrhMWaZMcnKFca4CQ,5073
+django_form_matrix/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+django_form_matrix/widgets.py,sha256=S19O90fRHBnIfaxVWdxQYPoqMtEkOI01NE-VdWD9aWI,4913
+django_form_matrix/contrib/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+django_form_matrix/contrib/permissions.py,sha256=FUlbA49zvrpWZ7BER4ZCNd_6tRGv7XYafRQsPdvWp2Y,6063
+django_form_matrix/contrib/unfold.py,sha256=5lD6314EIzQ0vPhjQKde6VeUP6hBSlN6nxQWE67FCfw,511
+django_form_matrix/locale/es/LC_MESSAGES/django.mo,sha256=hHE3PsJ4OIOeQV_d9vyx6PyZ50GMsbmWg3nAohXGzhA,1066
+django_form_matrix/locale/es/LC_MESSAGES/django.po,sha256=82TbUeBBK8AZy0dNxmcRyjWoMEePFESIf_3vb7Zj5jI,1664
+django_form_matrix/static/django_form_matrix/css/matrix.css,sha256=ysX0PndeZeWtHXe0kcxpmrl9AUNdTLsQwI-qFgW3tnY,3264
+django_form_matrix/static/django_form_matrix/css/unfold.css,sha256=WytH1lpM6W-O3vtQs5XbpeU02Hrb2wuDgBrdnJYZkhY,1199
+django_form_matrix/static/django_form_matrix/js/matrix.js,sha256=nXFSuYcw5fwcU6e3Bzxj5-WzQIwC_Gvmrr__8LAhAgM,2420
+django_form_matrix/templates/django_form_matrix/matrix.html,sha256=w3atBHQNHZo0N96FZzxOn_tC42g8KjUvkK6uONhzsIQ,2931
+django_form_matrix/templates/django_form_matrix/permissions.html,sha256=qJGRK_fFHUAcPOAHK-AK8jFbHDYajYt8FjCh0NICCU0,4275
+django_form_matrix-0.1.0.dist-info/METADATA,sha256=w-gS4RRUyithJcG2JLobWdV43o5js5LeHQ0XmIKpo10,10752
+django_form_matrix-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+django_form_matrix-0.1.0.dist-info/licenses/LICENSE,sha256=0EJi4J2ISkSQsH8fR7SQvn4J66zEouFMPErgIRKn0cg,1072
+django_form_matrix-0.1.0.dist-info/RECORD,,

django_form_matrix-0.1.0.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_form_matrix-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rodolfo Becerra
+
+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.