dj-design-system 0.1.0__tar.gz

dj_design_system-0.1.0/.gitignore

@@ -0,0 +1,52 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.egg-info/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Tools
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.tox/
+
+# Build outputs
+dist/
+build/
+# mkdocs build output
+site/
+
+# Coverage
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+
+# Databases
+*.db
+*.sqlite3
+
+# Secrets / local config
+.env
+.env.*
+!.env.example
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Editor
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Static files collected by Django
+staticfiles/

dj_design_system-0.1.0/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.0.1] - unreleased
+
+### Added
+
+- `TagComponent` and `BlockComponent` base classes for defining UI components
+- Parameter system: `StrParam`, `BoolParam`, `StrCSSClassParam`, `BoolCSSClassParam`, `ModelParam`, `UserParam`, `FieldParam`
+- Auto-discovery of components via Django's app registry (`AppConfig.ready()`)
+- Component registry with lookup, listing, and navigation tree APIs
+- Interactive gallery with live component previews in sandboxed iframes
+- Searchable navigation tree with folder, component, and documentation node types
+- Auto-generated templatetag usage examples from parameter definitions
+- `ComponentsStaticFinder` to serve per-component CSS/JS via Django staticfiles
+- Markdown documentation pages auto-discovered alongside components
+- Configurable canvas backgrounds, toolbar, and gallery settings via `dj_design_system` Django settings dict

dj_design_system-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,49 @@
+# Contributing to dj-design-system
+
+Thank you for taking the time to contribute!
+
+## Setting up a development environment
+
+**Prerequisites:** [uv](https://docs.astral.sh/uv/) and [just](https://just.systems/) must be installed.
+
+```bash
+git clone https://github.com/Django-Design-System/django_design_system.git
+cd django_design_system
+just install
+just install-hooks   # installs the pre-commit git hook
+just install-playwright  # installs Playwright browsers (needed for e2e tests)
+```
+
+## Running things locally
+
+| Command                   | Purpose                                             |
+| ------------------------- | --------------------------------------------------- |
+| `just test`               | Run all unit tests                                  |
+| `just test-one <pattern>` | Run tests matching a keyword                        |
+| `just e2e`                | Run Playwright end-to-end tests                     |
+| `just coverage`           | Unit tests with coverage report                     |
+| `just check`              | Lint and formatting check (no changes)              |
+| `just fix`                | Auto-fix all lint and formatting issues             |
+| `just typecheck`          | Run mypy type checking                              |
+| `just docs-serve`         | Serve the documentation site locally                |
+| `just demo`               | Start the example component gallery in your browser |
+
+The pre-commit hook installed by `just install-hooks` runs `just fix` automatically before every commit.
+
+## Code conventions
+
+- **Python style** is enforced by [ruff](https://docs.astral.sh/ruff/) — run `just fix` before committing.
+- **HTML/template style** is enforced by [djlint](https://djlint.com/) — also covered by `just fix`.
+- **Type annotations** are checked by [mypy](https://mypy-lang.org/) — run `just typecheck`.
+- Line length is 88 characters.
+- All new public classes and functions should have docstrings — they feed directly into the auto-generated API documentation.
+
+## Submitting a pull request
+
+1. Fork the repository and create a branch from `main`.
+2. Make your changes, add tests for any new behaviour.
+3. Run `just test` and `just check` — both must pass.
+4. Open a PR against `main`. All CI checks must be green before merging.
+5. A maintainer will review and merge.
+
+For bug reports or feature requests, please [open an issue](https://github.com/Django-Design-System/django_design_system/issues) first.

dj_design_system-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Department for Business and Trade
+
+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.

dj_design_system-0.1.0/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: dj-design-system
+Version: 0.1.0
+Summary: A Design System for Django
+Project-URL: Homepage, https://django-design-system.github.io/django_design_system/
+Project-URL: Repository, https://github.com/Django-Design-System/django_design_system
+Project-URL: Documentation, https://django-design-system.github.io/django_design_system/
+Project-URL: Bug Tracker, https://github.com/Django-Design-System/django_design_system/issues
+Project-URL: Changelog, https://github.com/Django-Design-System/django_design_system/blob/main/CHANGELOG.md
+Maintainer: marcelkornblum, CamLamb
+License: MIT
+License-File: LICENSE
+Keywords: Design System,component,django
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 5.2
+Classifier: Framework :: Django :: 6.0
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development :: User Interfaces
+Requires-Python: >=3.13
+Requires-Dist: django<8,>=5.2
+Requires-Dist: markdown
+Provides-Extra: dev
+Requires-Dist: djlint; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: types-markdown; extra == 'dev'
+Requires-Dist: types-pygments; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material; extra == 'docs'
+Requires-Dist: mkdocstrings-python; extra == 'docs'
+Provides-Extra: testing
+Requires-Dist: coverage; extra == 'testing'
+Requires-Dist: factory-boy; extra == 'testing'
+Requires-Dist: playwright; extra == 'testing'
+Requires-Dist: pytest-cov; extra == 'testing'
+Requires-Dist: pytest-django; extra == 'testing'
+Requires-Dist: pytest-mock; extra == 'testing'
+Requires-Dist: pytest-playwright; extra == 'testing'
+Description-Content-Type: text/markdown
+
+# dj-design-system
+
+[![CI](https://github.com/Django-Design-System/django_design_system/actions/workflows/ci.yml/badge.svg)](https://github.com/Django-Design-System/django_design_system/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/dj-design-system)](https://pypi.org/project/dj-design-system/)
+[![Python versions](https://img.shields.io/pypi/pyversions/dj-design-system)](https://pypi.org/project/dj-design-system/)
+[![Django](https://img.shields.io/badge/django-5.2%20%7C%206.0%20%7C%20latest-green)](https://www.djangoproject.com/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-yellow)](LICENSE)
+
+DjDS is a Django-native approach to writing front end components that are exposed as templatetags. It comes with an auto-generated, customisable, live interactive gallery of your UI components that lives alongside your Django project.
+
+Components are recognisably Django elements; they look and work like Models or Forms. The gallery auto-discovers them, renders live previews in sandboxed iframes, generates templatetag usage examples, and builds a searchable navigation tree — all from your existing code and docstrings.
+
+**[Browse the demo gallery →](https://django-design-system.github.io/django_design_system/gallery/)**
+
+## Quick start
+
+```bash
+pip install dj-design-system
+```
+
+Then follow the [quickstart guide](https://django-design-system.github.io/django_design_system/quickstart/) to register your first component.
+
+## Supported versions
+
+| Python | Django    |
+| ------ | --------- |
+| 3.13   | 5.2 (LTS) |
+| 3.14   | 6.0       |
+|        | latest    |
+
+## Documentation
+
+Full documentation is available at **[django-design-system.github.io/django_design_system/](https://django-design-system.github.io/django_design_system/)**.
+
+To browse locally:
+
+```bash
+just docs-serve
+```
+
+| Document                              | Contents                                  |
+| ------------------------------------- | ----------------------------------------- |
+| [Quick start](docs/quickstart.md)     | Installation and first component          |
+| [Components](docs/components.md)      | Defining components and parameters        |
+| [Registry](docs/registry.md)          | Auto-discovery and the component registry |
+| [Gallery](docs/gallery.md)            | Configuring and customising the gallery   |
+| [Template tags](docs/templatetags.md) | Using components in templates             |
+| [API reference](docs/api/)            | Auto-generated class and parameter docs   |
+
+A static snapshot of the component gallery is browseable at **[django-design-system.github.io/django_design_system/gallery/](https://django-design-system.github.io/django_design_system/gallery/)** (HTMX interactions disabled; run `just demo` for the full live experience).
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for how to set up a dev environment, run tests, and submit a pull request.
+
+## Code of conduct
+
+This project follows the [Contributor Covenant](https://www.contributor-covenant.org/). Please read [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) before contributing.
+
+## Issues and feature requests
+
+Please open an issue on [GitHub](https://github.com/Django-Design-System/django_design_system/issues). Use the bug report template for defects and the feature request template for new ideas.
+
+## Security
+
+To report a vulnerability privately, see [SECURITY.md](SECURITY.md).
+
+## Licence
+
+[MIT](LICENSE)
+
+With thanks to the UK [Department for Business and Trade](https://github.com/uktrade), where this was originally developed.

dj_design_system-0.1.0/README.md

@@ -0,0 +1,72 @@
+# dj-design-system
+
+[![CI](https://github.com/Django-Design-System/django_design_system/actions/workflows/ci.yml/badge.svg)](https://github.com/Django-Design-System/django_design_system/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/dj-design-system)](https://pypi.org/project/dj-design-system/)
+[![Python versions](https://img.shields.io/pypi/pyversions/dj-design-system)](https://pypi.org/project/dj-design-system/)
+[![Django](https://img.shields.io/badge/django-5.2%20%7C%206.0%20%7C%20latest-green)](https://www.djangoproject.com/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-yellow)](LICENSE)
+
+DjDS is a Django-native approach to writing front end components that are exposed as templatetags. It comes with an auto-generated, customisable, live interactive gallery of your UI components that lives alongside your Django project.
+
+Components are recognisably Django elements; they look and work like Models or Forms. The gallery auto-discovers them, renders live previews in sandboxed iframes, generates templatetag usage examples, and builds a searchable navigation tree — all from your existing code and docstrings.
+
+**[Browse the demo gallery →](https://django-design-system.github.io/django_design_system/gallery/)**
+
+## Quick start
+
+```bash
+pip install dj-design-system
+```
+
+Then follow the [quickstart guide](https://django-design-system.github.io/django_design_system/quickstart/) to register your first component.
+
+## Supported versions
+
+| Python | Django    |
+| ------ | --------- |
+| 3.13   | 5.2 (LTS) |
+| 3.14   | 6.0       |
+|        | latest    |
+
+## Documentation
+
+Full documentation is available at **[django-design-system.github.io/django_design_system/](https://django-design-system.github.io/django_design_system/)**.
+
+To browse locally:
+
+```bash
+just docs-serve
+```
+
+| Document                              | Contents                                  |
+| ------------------------------------- | ----------------------------------------- |
+| [Quick start](docs/quickstart.md)     | Installation and first component          |
+| [Components](docs/components.md)      | Defining components and parameters        |
+| [Registry](docs/registry.md)          | Auto-discovery and the component registry |
+| [Gallery](docs/gallery.md)            | Configuring and customising the gallery   |
+| [Template tags](docs/templatetags.md) | Using components in templates             |
+| [API reference](docs/api/)            | Auto-generated class and parameter docs   |
+
+A static snapshot of the component gallery is browseable at **[django-design-system.github.io/django_design_system/gallery/](https://django-design-system.github.io/django_design_system/gallery/)** (HTMX interactions disabled; run `just demo` for the full live experience).
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for how to set up a dev environment, run tests, and submit a pull request.
+
+## Code of conduct
+
+This project follows the [Contributor Covenant](https://www.contributor-covenant.org/). Please read [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) before contributing.
+
+## Issues and feature requests
+
+Please open an issue on [GitHub](https://github.com/Django-Design-System/django_design_system/issues). Use the bug report template for defects and the feature request template for new ideas.
+
+## Security
+
+To report a vulnerability privately, see [SECURITY.md](SECURITY.md).
+
+## Licence
+
+[MIT](LICENSE)
+
+With thanks to the UK [Department for Business and Trade](https://github.com/uktrade), where this was originally developed.

dj_design_system-0.1.0/dj_design_system/__init__.py

@@ -0,0 +1 @@
+from dj_design_system.services.registry import component_registry  # noqa: F401

dj_design_system-0.1.0/dj_design_system/apps.py

@@ -0,0 +1,13 @@
+from django.apps import AppConfig
+
+
+class DjangoDesignSystemConfig(AppConfig):
+    """App configuration for dj_design_system."""
+
+    name = "dj_design_system"
+    default_auto_field = "django.db.models.BigAutoField"
+
+    def ready(self) -> None:
+        from dj_design_system import component_registry
+
+        component_registry.autodiscover()

dj_design_system-0.1.0/dj_design_system/components.py

@@ -0,0 +1,293 @@
+from typing import TYPE_CHECKING, Any
+
+from django.utils.html import format_html
+from django.utils.safestring import SafeString
+
+from dj_design_system.parameters import BaseParam
+
+
+if TYPE_CHECKING:
+    from dj_design_system.data import ComponentMedia
+
+
+class BaseComponent:
+    # The template string itself to pass to format_html. Should be overridden by subclasses.
+    template_format_str: str = "<span class='{classes}'>ABSTRACT COMPONENT</span>"
+
+    class Meta:
+        abstract = True
+
+    def __init_subclass__(cls, **kwargs) -> None:
+        """Validate Meta constraint declarations at class definition time."""
+        super().__init_subclass__(**kwargs)
+        from dj_design_system.services.component import get_own_meta, is_abstract
+
+        if is_abstract(cls):
+            return
+
+        meta = get_own_meta(cls)
+        param_names = set(cls.get_params().keys())
+
+        for a, b in getattr(meta, "mutually_exclusive", []):
+            for name in (a, b):
+                if name not in param_names:
+                    raise ValueError(
+                        f"{cls.__name__}.Meta.mutually_exclusive references unknown param '{name}'."
+                    )
+
+        for dependent, dependency in getattr(meta, "requires", []):
+            for name in (dependent, dependency):
+                if name not in param_names:
+                    raise ValueError(
+                        f"{cls.__name__}.Meta.requires references unknown param '{name}'."
+                    )
+
+    def __init__(self, **kwargs):
+        self.context = {}
+        for var_name, var_value in kwargs.items():
+            setattr(self, var_name, var_value)
+
+        self._validate_meta_constraints()
+        self.validate_params()
+
+    def validate_params(self) -> None:
+        """An override hook allowing param combinations or values to raise exceptions if necessary"""
+        ...
+
+    def _validate_meta_constraints(self) -> None:
+        """Enforce mutually_exclusive and requires constraints declared on Meta.
+
+        Called automatically during __init__ before validate_params.
+        - Meta.mutually_exclusive: list of (param_a, param_b) pairs that cannot both be set.
+        - Meta.requires: list of (dependent, dependency) pairs where setting dependent
+          requires dependency to also be set.
+        """
+        from dj_design_system.services.component import get_own_meta
+
+        params = type(self).get_params()
+        meta = get_own_meta(type(self))
+
+        for a, b in getattr(meta, "mutually_exclusive", []):
+            if params[a].has_been_set(self) and params[b].has_been_set(self):
+                raise ValueError(
+                    f"'{a}' and '{b}' cannot both be set on {type(self).__name__}."
+                )
+
+        for dependent, dependency in getattr(meta, "requires", []):
+            if params[dependent].has_been_set(self) and not params[
+                dependency
+            ].has_been_set(self):
+                raise ValueError(
+                    f"'{dependent}' requires '{dependency}' to also be set on {type(self).__name__}."
+                )
+
+    def get_context(self) -> dict[str, Any]:
+        """
+        Get the context for rendering the component. This method can be overridden by subclasses to add additional or edit other context variables.
+        """
+        self.context["classes"] = self.get_classes_string()
+        for param_name, spec in self.params.items():
+            value = getattr(self, param_name)
+            self.context[param_name] = value
+            self.context.update(spec.get_extra_context(param_name, value))
+        return self.context
+
+    def get_classes_string(self):
+        """
+        Get a string of CSS classes based on the context. This can be used in the template to apply conditional styling.
+        """
+        classes = []
+        for param_name, spec in self.params.items():
+            param_value = getattr(self, param_name)
+            classes.extend(spec.get_css_classes(param_name, param_value))
+        return " ".join(classes)
+
+    def render(self) -> str:
+        """
+        Render the component as an HTML string.
+        """
+        return format_html(format_string=self.template_format_str, **self.get_context())
+
+    def __str__(self) -> str:
+        return self.render()
+
+    def __html__(self) -> str:
+        return self.render()
+
+    @property
+    def description(self) -> str | None:
+        return self.__doc__
+
+    @property
+    def params(self) -> dict[str, "BaseParam"]:
+        return type(self).get_params()
+
+    @classmethod
+    def get_params(cls) -> dict[str, "BaseParam"]:
+        """
+        Get the parameters for this component. Returns a dictionary of all
+        BaseParam descriptors defined on the class (or any subclass in the MRO).
+        """
+        result = {}
+        for klass in cls.__mro__:
+            for attr_name, attr_value in vars(klass).items():
+                if isinstance(attr_value, BaseParam) and attr_name not in result:
+                    result[attr_name] = attr_value
+        return result
+
+    @classmethod
+    def docstring(cls) -> str:
+        """
+        Return a string describing the API of this component, including its parameters and their types.
+        """
+        params = cls.get_params()
+        api_docs = f"{cls.__doc__}\n\n"
+        if len(params) > 0:
+            api_docs += "Parameters:\n"
+        for parameter_spec in params.values():
+            api_docs += f"- {parameter_spec.docstring()}\n"
+        return api_docs
+
+    @classmethod
+    def get_name(cls) -> str:
+        """Return the component's registered name from the registry."""
+        from dj_design_system import component_registry
+
+        return component_registry.get_info(cls).name
+
+    @classmethod
+    def get_app_label(cls) -> str:
+        """Return the app label this component was discovered in."""
+        from dj_design_system import component_registry
+
+        return component_registry.get_info(cls).app_label
+
+    @classmethod
+    def get_relative_path(cls) -> str:
+        """Return the relative path within the app's components directory."""
+        from dj_design_system import component_registry
+
+        return component_registry.get_info(cls).relative_path
+
+    @classmethod
+    def get_media(cls) -> "ComponentMedia":
+        """Return the CSS and JS static URL paths required by this component.
+
+        Delegates to ``ComponentInfo.media`` — see that property for full
+        documentation of auto-discovery and ``Media`` class override behaviour.
+        """
+        from dj_design_system import component_registry
+
+        return component_registry.get_info(cls).media
+
+    @classmethod
+    def get_positional_args(cls) -> list[str]:
+        """Return the list of positional arg names from the class's own Meta.positional_args.
+
+        Only looks at the class's own ``Meta`` — positional_args are NOT
+        inherited from parent classes, matching Django's convention that
+        Meta is not inherited. This avoids silent ordering surprises when
+        subclassing.
+        """
+        from dj_design_system.services.component import get_own_meta
+
+        meta = get_own_meta(cls)
+        positional = getattr(meta, "positional_args", None)
+        return list(positional) if positional else []
+
+    @staticmethod
+    def map_positional_args(
+        positional_args: list[str], args: tuple, kwargs: dict
+    ) -> dict:
+        """Map positional arguments to keyword arguments using the positional_args spec."""
+        for i, arg_name in enumerate(positional_args):
+            if i < len(args):
+                kwargs[arg_name] = args[i]
+        return kwargs
+
+
+class TagComponent(BaseComponent):
+    """
+    A component registered as a Django ``simple_tag``.
+
+    Subclass this for components that produce a single HTML fragment
+    without wrapping nested template content.
+
+    Use ``Meta.positional_args`` to declare parameters that can be passed
+    as positional arguments in the template tag::
+
+        class IconComponent(TagComponent):
+            name = StrParam("The icon name.")
+
+            class Meta:
+                positional_args = ["name"]
+
+    This allows ``{% icon "check" %}`` instead of ``{% icon name="check" %}``.
+    """
+
+    class Meta:
+        abstract = True
+
+    @classmethod
+    def as_tag(cls):
+        """Return a template tag function mapping positional args via Meta.positional_args."""
+        positional_args = cls.get_positional_args()
+
+        def _tag(*args, **kwargs):
+            cls.map_positional_args(positional_args, args, kwargs)
+            return cls(**kwargs)
+
+        return _tag
+
+
+class BlockComponent(BaseComponent):
+    """
+    A component registered as a Django ``simple_block_tag``, allowing
+    for nested template content.
+
+    The template should include a ``{content}`` placeholder where the
+    inner content will be rendered. ``content`` is always the first
+    positional argument and should NOT appear in ``Meta.positional_args``.
+
+    Use ``Meta.positional_args`` to declare additional positional args
+    beyond ``content``::
+
+        class SectionComponent(BlockComponent):
+            title = StrParam("Section title.")
+
+            class Meta:
+                positional_args = ["title"]
+
+    This allows ``{% section "My Title" %}...{% endsection %}``.
+    """
+
+    class Meta:
+        abstract = True
+
+    template_format_str: str = "<span class='{classes}'>{content}</span>"
+
+    def __init__(self, content: SafeString, **kwargs):
+        self.content = content
+        super().__init__(**kwargs)
+
+    def get_context(self) -> dict[str, Any]:
+        """Add ``content`` to the context automatically.
+
+        ``content`` is the block body passed by the template engine — it is
+        NOT a declared BaseParam and should not appear in ``Meta.positional_args``
+        or ``docstring()`` output.
+        """
+        context = super().get_context()
+        context["content"] = self.content
+        return context
+
+    @classmethod
+    def as_tag(cls):
+        """Return a template tag function with content as first arg, plus any Meta.positional_args."""
+        positional_args = cls.get_positional_args()
+
+        def _tag(content, *args, **kwargs):
+            cls.map_positional_args(positional_args, args, kwargs)
+            return cls(content=content, **kwargs)
+
+        return _tag