django-trellis 0.1.0__tar.gz

django_trellis-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+node_modules/
+.pnpm-store/
+.venv/
+dist/
+build/
+*.egg-info/
+.vite/
+.ruff_cache/
+.pytest_cache/
+__pycache__/
+*.pyc
+.DS_Store
+.idea/
+.coverage
+coverage/
+htmlcov/
+playwright-report/
+test-results/
+/types/
+/trellis_ui/static/trellis_ui/css/styles.css
+/trellis_ui/static/trellis_ui/js/
+/trellis_ui/static/trellis_ui/manifests/
+/trellis_ui/generated_styles.py
+/docs/static/docs/
+*.map
+.agents/
+docs/
+/vite.docs.config.ts

django_trellis-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tristan Robinette
+
+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_trellis-0.1.0/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: django-trellis
+Version: 0.1.0
+Summary: Token-driven Django Cotton UI component kit.
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Framework :: Django
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.13
+Requires-Dist: django-cotton>=2.7.2
+Requires-Dist: django-eventstream>=5.3.4
+Requires-Dist: django>=6.0
+Description-Content-Type: text/markdown
+
+# Trellis UI

django_trellis-0.1.0/README.md

@@ -0,0 +1 @@
+# Trellis UI

django_trellis-0.1.0/pyproject.toml

@@ -0,0 +1,88 @@
+[project]
+name = "django-trellis"
+version = "0.1.0"
+description = "Token-driven Django Cotton UI component kit."
+readme = "README.md"
+requires-python = ">=3.13"
+license = "MIT"
+classifiers = [
+    "Framework :: Django",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+]
+dependencies = [
+    "django>=6.0",
+    "django-cotton>=2.7.2",
+    "django-eventstream>=5.3.4",
+]
+
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build]
+artifacts = [
+    "/trellis_ui/static/trellis_ui/css/styles.css",
+    "/trellis_ui/static/trellis_ui/js/index.js",
+    "/trellis_ui/generated_styles.py",
+]
+exclude = [
+    "/.gitignore",
+    "**/__pycache__",
+    "**/*.pyc",
+]
+
+[dependency-groups]
+dev = [
+    "daphne>=4.2.1",
+    "djlint>=1.40.1",
+    "prek>=0.4.6",
+    "pytest>=9.1.0",
+    "pytest-django>=4.12.0",
+    "ruff>=0.15.17",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["trellis_ui"]
+exclude = [
+    "/trellis_ui/static/trellis_ui/js/**/*.map",
+    "/trellis_ui/static/trellis_ui/js/esm",
+    "/trellis_ui/static/trellis_ui/manifests",
+]
+
+[tool.hatch.build.targets.sdist]
+only-include = [
+    "trellis_ui",
+    "README.md",
+    "LICENSE",
+    "pyproject.toml",
+]
+exclude = [
+    "/.gitignore",
+    "/trellis_ui/static/trellis_ui/js/**/*.map",
+    "/trellis_ui/static/trellis_ui/js/esm",
+    "/trellis_ui/static/trellis_ui/manifests",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py313"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "DJ", "RUF"]
+ignore = []
+
+[tool.djlint]
+profile = "django"
+extension = "html"
+ignore = "H006,H021,H026,H030,H031,H037"
+custom_html = "c-[\\w-\\.]+"
+blank_line_after_tag = "c-vars,endpartialdef,load,extends,include,c-slot"
+blank_line_before_tag = "partialdef"
+max_attribute_length = 80
+
+[tool.pytest.ini_options]
+DJANGO_SETTINGS_MODULE = "tests.testapp.settings"
+pythonpath = ["."]
+python_files = ["test_*.py", "*_test.py"]
+testpaths = ["tests/components"]

django_trellis-0.1.0/trellis_ui/__init__.py

@@ -0,0 +1,30 @@
+from .forms import (
+    BaseForm,
+    BaseFormMixin,
+    BaseFormSet,
+    BaseModelForm,
+    BaseModelFormSet,
+    ComboboxSelect,
+    DatePickerInput,
+    DateRangePickerInput,
+    WidgetContext,
+    widget_adapter,
+)
+from .stream import UI, ctx
+from .targets import UITargets
+
+__all__ = [
+    "UI",
+    "BaseForm",
+    "BaseFormMixin",
+    "BaseFormSet",
+    "BaseModelForm",
+    "BaseModelFormSet",
+    "ComboboxSelect",
+    "DatePickerInput",
+    "DateRangePickerInput",
+    "UITargets",
+    "WidgetContext",
+    "ctx",
+    "widget_adapter",
+]

django_trellis-0.1.0/trellis_ui/apps.py

@@ -0,0 +1,6 @@
+from django.apps import AppConfig
+
+
+class TrellisUIConfig(AppConfig):
+    name = "trellis_ui"
+    verbose_name = "Trellis UI"

django_trellis-0.1.0/trellis_ui/context_processors.py

@@ -0,0 +1,6 @@
+from .stream import ctx
+
+
+def ui(_) -> dict:
+    return ctx()
+

django_trellis-0.1.0/trellis_ui/events.py

@@ -0,0 +1,15 @@
+
+from enum import StrEnum
+
+
+class UIEvents(StrEnum):
+    MODAL_CLOSE = "ui:modal-close"
+    RESIZE = "ui:resize"
+    RESIZE_END = "ui:resize-end"
+    RESIZE_START = "ui:resize-start"
+    SIDEBAR_CLOSE = "ui:sidebar-close"
+    SIDEBAR_OPEN = "ui:sidebar-open"
+    TOAST = "ui:toast"
+
+
+__all__ = ["UIEvents"]

django_trellis-0.1.0/trellis_ui/filters/__init__.py

@@ -0,0 +1,3 @@
+from trellis_ui.filters import rules
+
+__all__ = ["rules"]

django_trellis-0.1.0/trellis_ui/filters/rules.py

@@ -0,0 +1,148 @@
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from types import MappingProxyType
+from typing import Any, Self
+
+type JSONValue = str | int | float | bool | None | list[JSONValue] | dict[str, JSONValue]
+
+
+@dataclass(frozen=True)
+class RuleSpec[TValue]:
+    kind: str
+    field_path: str | None = None
+    operation_value: TValue | None = None
+    model: str | None = None
+    negate: bool = False
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "kind", _validate_non_empty_string("kind", self.kind))
+        object.__setattr__(
+            self,
+            "field_path",
+            _validate_optional_non_empty_string("field_path", self.field_path),
+        )
+        object.__setattr__(self, "model", _validate_optional_string("model", self.model))
+
+        if not isinstance(self.negate, bool):
+            raise TypeError("negate must be a boolean.")
+
+        object.__setattr__(self, "metadata", _immutable_metadata(self.metadata))
+
+    def to_dict(self) -> dict[str, JSONValue]:
+        return {
+            "kind": self.kind,
+            "field_path": self.field_path,
+            "operation_value": _json_value(self.operation_value, name="operation_value"),
+            "model": self.model,
+            "negate": self.negate,
+            "metadata": _json_object(self.metadata, name="metadata"),
+        }
+
+    @classmethod
+    def from_dict(cls, data: Mapping[str, Any]) -> Self:
+        if not isinstance(data, Mapping):
+            raise TypeError("RuleSpec.from_dict() expects a mapping.")
+
+        try:
+            kind = data["kind"]
+        except KeyError as error:
+            raise ValueError("RuleSpec data must include kind.") from error
+
+        field_path = data.get("field_path")
+        operation_value = data.get("operation_value")
+        model = data.get("model")
+        negate = data.get("negate", False)
+        metadata = data.get("metadata", {})
+
+        _json_value(operation_value, name="operation_value")
+        _json_object(metadata, name="metadata")
+
+        return cls(
+            kind=kind,
+            field_path=field_path,
+            operation_value=operation_value,
+            model=model,
+            negate=negate,
+            metadata=metadata,
+        )
+
+
+def spec[TValue](
+    kind: str,
+    *,
+    field_path: str | None = None,
+    operation_value: TValue | None = None,
+    model: str | None = None,
+    negate: bool = False,
+    metadata: Mapping[str, Any] | None = None,
+    **metadata_values: Any,
+) -> RuleSpec[TValue]:
+    merged_metadata: dict[str, Any] = {}
+    if metadata is not None:
+        merged_metadata.update(_json_object(metadata, name="metadata"))
+    merged_metadata.update(metadata_values)
+
+    return RuleSpec(
+        kind=kind,
+        field_path=field_path,
+        operation_value=operation_value,
+        model=model,
+        negate=negate,
+        metadata=merged_metadata,
+    )
+
+
+def _validate_non_empty_string(name: str, value: Any) -> str:
+    if not isinstance(value, str):
+        raise TypeError(f"{name} must be a string.")
+    if value == "":
+        raise ValueError(f"{name} must not be empty.")
+    return value
+
+
+def _validate_optional_non_empty_string(name: str, value: Any) -> str | None:
+    if value is None:
+        return None
+    return _validate_non_empty_string(name, value)
+
+
+def _validate_optional_string(name: str, value: Any) -> str | None:
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        raise TypeError(f"{name} must be a string.")
+    return value
+
+
+def _immutable_metadata(metadata: Mapping[str, Any]) -> Mapping[str, Any]:
+    return MappingProxyType(_json_object(metadata, name="metadata"))
+
+
+def _json_object(value: Any, *, name: str) -> dict[str, JSONValue]:
+    if not isinstance(value, Mapping):
+        raise TypeError(f"{name} must be a mapping.")
+
+    output: dict[str, JSONValue] = {}
+    for key, item in value.items():
+        if not isinstance(key, str):
+            raise TypeError(f"{name} keys must be strings.")
+        output[key] = _json_value(item, name=f"{name}.{key}")
+    return output
+
+
+def _json_value(value: Any, *, name: str) -> JSONValue:
+    if value is None or isinstance(value, str | int | float | bool):
+        return value
+
+    if isinstance(value, Mapping):
+        return _json_object(value, name=name)
+
+    if _is_json_sequence(value):
+        return [_json_value(item, name=name) for item in value]
+
+    raise TypeError(f"{name} must be JSON-compatible.")
+
+
+def _is_json_sequence(value: Any) -> bool:
+    return isinstance(value, Sequence) and not isinstance(value, str | bytes | bytearray)

django_trellis-0.1.0/trellis_ui/forms/__init__.py

@@ -0,0 +1,22 @@
+from trellis_ui.forms.base import BaseForm, BaseFormMixin, BaseModelForm
+from trellis_ui.forms.formsets import BaseFormSet, BaseModelFormSet
+from trellis_ui.forms.widgets import (
+    ComboboxSelect,
+    DatePickerInput,
+    DateRangePickerInput,
+    WidgetContext,
+    widget_adapter,
+)
+
+__all__ = [
+    "BaseForm",
+    "BaseFormMixin",
+    "BaseFormSet",
+    "BaseModelForm",
+    "BaseModelFormSet",
+    "ComboboxSelect",
+    "DatePickerInput",
+    "DateRangePickerInput",
+    "WidgetContext",
+    "widget_adapter",
+]

django_trellis-0.1.0/trellis_ui/forms/base.py

@@ -0,0 +1,23 @@
+from django import forms
+
+from trellis_ui.forms.renderers import TrellisUIRenderer
+
+
+class BaseFormMixin:
+    default_renderer = TrellisUIRenderer
+    template_name_div = TrellisUIRenderer.form_template_name
+    template_name_p = TrellisUIRenderer.form_template_name
+    template_name_table = TrellisUIRenderer.form_template_name
+    template_name_ul = TrellisUIRenderer.form_template_name
+
+    def __init__(self, *args, **kwargs):
+        kwargs.setdefault("label_suffix", "")
+        super().__init__(*args, **kwargs)
+
+
+class BaseForm(BaseFormMixin, forms.Form):
+    pass
+
+
+class BaseModelForm(BaseFormMixin, forms.ModelForm):
+    pass

django_trellis-0.1.0/trellis_ui/forms/boundfield.py

@@ -0,0 +1,33 @@
+from django.forms.boundfield import BoundField
+
+from trellis_ui.forms.widgets import render_bound_widget
+
+
+class UIBoundField(BoundField):
+    def as_widget(self, widget=None, attrs=None, only_initial=False):
+        widget = widget or self.field.widget
+        if self.field.localize:
+            widget.is_localized = True
+        attrs = attrs or {}
+        attrs = self.build_widget_attrs(attrs, widget)
+        if self.auto_id and "id" not in widget.attrs:
+            attrs.setdefault(
+                "id",
+                self.html_initial_id if only_initial else self.auto_id,
+            )
+        if only_initial and self.html_initial_name in self.form.data:
+            value = self.form._widget_data_value(
+                self.field.hidden_widget(),
+                self.html_initial_name,
+            )
+        else:
+            value = self.value()
+
+        return render_bound_widget(
+            bound_field=self,
+            widget=widget,
+            name=self.html_initial_name if only_initial else self.html_name,
+            value=value,
+            attrs=attrs,
+            renderer=self.form.renderer,
+        )

django_trellis-0.1.0/trellis_ui/forms/formsets.py

@@ -0,0 +1,20 @@
+from django.forms.formsets import BaseFormSet as DjangoBaseFormSet
+from django.forms.models import BaseModelFormSet as DjangoBaseModelFormSet
+
+from trellis_ui.forms.renderers import TrellisUIRenderer
+
+
+class BaseFormSet(DjangoBaseFormSet):
+    renderer = TrellisUIRenderer()
+    template_name_div = TrellisUIRenderer.formset_template_name
+    template_name_p = TrellisUIRenderer.formset_template_name
+    template_name_table = TrellisUIRenderer.formset_template_name
+    template_name_ul = TrellisUIRenderer.formset_template_name
+
+
+class BaseModelFormSet(DjangoBaseModelFormSet):
+    renderer = TrellisUIRenderer()
+    template_name_div = TrellisUIRenderer.formset_template_name
+    template_name_p = TrellisUIRenderer.formset_template_name
+    template_name_table = TrellisUIRenderer.formset_template_name
+    template_name_ul = TrellisUIRenderer.formset_template_name

django_trellis-0.1.0/trellis_ui/forms/presets/__init__.py

@@ -0,0 +1,3 @@
+from trellis_ui.forms.presets import dates
+
+__all__ = ["dates"]

django_trellis-0.1.0/trellis_ui/forms/presets/dates.py

@@ -0,0 +1,164 @@
+from calendar import monthrange
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from datetime import date, timedelta
+from types import MappingProxyType
+from typing import Any
+
+from django.utils import timezone
+
+from trellis_ui.filters import rules
+from trellis_ui.filters.rules import RuleSpec
+
+
+@dataclass(frozen=True)
+class DatePreset:
+    value: str
+    label: str
+    start: date
+    end: date
+    rule: RuleSpec[dict[str, int]] | None = None
+    disabled: bool = False
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if not self.value:
+            raise ValueError("DatePreset value must not be empty.")
+        if not self.label:
+            raise ValueError("DatePreset label must not be empty.")
+        if self.start > self.end:
+            raise ValueError("DatePreset start must be before or equal to end.")
+        object.__setattr__(self, "metadata", MappingProxyType(dict(self.metadata)))
+
+    def to_dict(self) -> dict[str, str | bool]:
+        data: dict[str, str | bool] = {
+            "value": self.value,
+            "label": self.label,
+            "start": self.start.isoformat(),
+            "end": self.end.isoformat(),
+        }
+        if self.disabled:
+            data["disabled"] = True
+        return data
+
+
+def today(
+    *,
+    label: str = "Today",
+    value: str = "today",
+    today: date | None = None,
+) -> DatePreset:
+    current = _today(today)
+    return DatePreset(value=value, label=label, start=current, end=current)
+
+
+def yesterday(
+    *,
+    label: str = "Yesterday",
+    value: str = "yesterday",
+    today: date | None = None,
+) -> DatePreset:
+    current = _today(today) - timedelta(days=1)
+    return DatePreset(value=value, label=label, start=current, end=current)
+
+
+def since(
+    *,
+    days: int | None = None,
+    months: int | None = None,
+    years: int | None = None,
+    label: str | None = None,
+    value: str | None = None,
+    include_today: bool = True,
+    today: date | None = None,
+    field: str | None = None,
+    model: str | None = None,
+) -> DatePreset:
+    units = {
+        key: amount
+        for key, amount in {"days": days, "months": months, "years": years}.items()
+        if amount is not None
+    }
+    if len(units) != 1:
+        raise ValueError("dates.since() expects exactly one of days, months, or years.")
+
+    unit, amount = next(iter(units.items()))
+    if amount <= 0:
+        raise ValueError("dates.since() amount must be greater than zero.")
+
+    end = _today(today) if include_today else _today(today) - timedelta(days=1)
+    if unit == "days":
+        start = end - timedelta(days=amount - 1)
+    elif unit == "months":
+        start = _add_months(end, -amount)
+    else:
+        start = _add_years(end, -amount)
+
+    preset_value = value or f"last_{amount}_{unit}"
+    preset_label = label or f"Last {amount} {unit}"
+    rule = None
+    if field is not None or model is not None:
+        rule = rules.spec(
+            kind="since",
+            field_path=field,
+            operation_value={unit: amount},
+            model=model,
+            metadata={"preset": preset_value},
+        )
+
+    return DatePreset(
+        value=preset_value,
+        label=preset_label,
+        start=start,
+        end=end,
+        rule=rule,
+    )
+
+
+def normalize_preset(preset: DatePreset | Mapping[str, Any]) -> dict[str, str | bool]:
+    if isinstance(preset, DatePreset):
+        return preset.to_dict()
+    if not isinstance(preset, Mapping):
+        raise ValueError("Date picker presets must be DatePreset instances or mappings.")
+
+    output: dict[str, str | bool] = {}
+    for key in ("value", "label", "start", "end"):
+        value = preset.get(key)
+        if value in (None, ""):
+            raise ValueError(f"Date picker preset mappings must include {key}.")
+        output[key] = _iso_value(value, key=key)
+
+    disabled = preset.get("disabled", False)
+    if disabled:
+        output["disabled"] = True
+    return output
+
+
+def _today(today: date | None) -> date:
+    return today or timezone.localdate()
+
+
+def _iso_value(value: Any, *, key: str) -> str:
+    if isinstance(value, date):
+        return value.isoformat()
+    if isinstance(value, str):
+        return value
+    raise ValueError(f"Date picker preset {key} must be a date or ISO date string.")
+
+
+def _add_months(value: date, months: int) -> date:
+    month_index = value.month - 1 + months
+    year = value.year + month_index // 12
+    month = month_index % 12 + 1
+    day = min(value.day, monthrange(year, month)[1])
+    return value.replace(year=year, month=month, day=day)
+
+
+def _add_years(value: date, years: int) -> date:
+    try:
+        return value.replace(year=value.year + years)
+    except ValueError:
+        return value.replace(year=value.year + years, day=28)
+
+
+__all__ = ["DatePreset", "normalize_preset", "since", "today", "yesterday"]

django_trellis-0.1.0/trellis_ui/forms/renderers.py

@@ -0,0 +1,21 @@
+from django.forms.renderers import DjangoTemplates, TemplatesSetting
+from django.template.exceptions import TemplateDoesNotExist
+
+from trellis_ui.forms.boundfield import UIBoundField
+
+BUILTIN_RENDERER = DjangoTemplates()
+
+
+class TrellisUIRenderer(TemplatesSetting):
+    form_template_name = "trellis_ui/forms/form.html"
+    formset_template_name = "trellis_ui/forms/formset.html"
+    field_template_name = "trellis_ui/forms/field.html"
+    bound_field_class = UIBoundField
+
+    def get_template(self, template_name):
+        try:
+            return super().get_template(template_name)
+        except TemplateDoesNotExist:
+            if template_name.startswith("django/forms/"):
+                return BUILTIN_RENDERER.get_template(template_name)
+            raise