shrd 0.3.0__tar.gz

shrd-0.3.0/LICENSE

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

shrd-0.3.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: shrd
+Version: 0.3.0
+Summary: A Django-native component framework with props, state, HTMX, and Alpine.js
+Author: Shard Contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/kurtisrogers/Shard
+Project-URL: Documentation, https://kurtisrogers.github.io/Shard/
+Keywords: django,components,htmx,alpine,shard
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 5.1
+Classifier: Framework :: Django :: 6.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Django>=4.2
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-django>=4.8; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.9.0; extra == "dev"
+Requires-Dist: pre-commit>=4.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == "docs"
+Dynamic: license-file
+
+# Shard
+
+A Django-native component framework for building UI with **props**, **server state**, **slots**, and **scoped styles** — using only the Django ecosystem plus bundled HTMX and Alpine.js.
+
+📖 **[Full documentation](https://kurtisrogers.github.io/Shard/)**
+
+Shard is a framework, not a drop-in library. Your Django project adopts its conventions: components live in your apps, templates sit beside scoped CSS, and HTMX carries server actions.
+
+## Philosophy
+
+Shard does not ship a widget catalog. It gives you a small, familiar model — closer to React/Vue than to Django templates alone — without a build step or SPA complexity:
+
+- **Props** — typed inputs declared on a Python class
+- **State** — server-owned data updated via `@action` methods
+- **Slots** — wrap and compose markup like `children` / default slots
+- **Scoped styles** — co-located `.css` files, automatically prefixed to the component
+- **Computed** — derived values via `@computed` methods
+- **Events** — HTMX custom events via `@emits` and `ActionResult`
+- **HTMX** — partial re-renders after actions
+- **Alpine.js** — optional client-side behavior inside templates
+- **View data** — optional structured layouts, mutable via `ViewTreeComponent`
+
+## Quick start
+
+```python
+# myapp/components.py
+from shard import Component, Prop, action
+
+class Card(Component):
+    title = Prop(str, default="")
+    template_name = "components/card.html"
+```
+
+```django
+{% load shard %}
+{% shard_scripts %}
+
+{% component Card title="Profile" %}
+  <p>Anything here is passed through the default slot.</p>
+{% endcomponent %}
+```
+
+See the [quickstart guide](https://kurtisrogers.github.io/Shard/getting-started/quickstart/) for a full walkthrough.
+
+## Documentation
+
+| Topic          | Link                                                                                               |
+| -------------- | -------------------------------------------------------------------------------------------------- |
+| Installation   | [getting-started/installation](https://kurtisrogers.github.io/Shard/getting-started/installation/) |
+| Components     | [concepts/components](https://kurtisrogers.github.io/Shard/concepts/components/)                   |
+| Slots          | [concepts/slots](https://kurtisrogers.github.io/Shard/concepts/slots/)                             |
+| Scoped styles  | [concepts/styles](https://kurtisrogers.github.io/Shard/concepts/styles/)                           |
+| Actions & HTMX | [interactivity/actions](https://kurtisrogers.github.io/Shard/interactivity/actions/)               |
+| HTMX & Alpine  | [guides/htmx-and-alpine](https://kurtisrogers.github.io/Shard/guides/htmx-and-alpine/)             |
+| View data      | [guides/view-data](https://kurtisrogers.github.io/Shard/guides/view-data/)                         |
+| API reference  | [reference/api](https://kurtisrogers.github.io/Shard/reference/api/)                               |
+| Examples       | [examples](https://kurtisrogers.github.io/Shard/examples/)                                         |
+
+## Example app
+
+```bash
+pip install shrd[dev]
+cd example
+python manage.py migrate
+python manage.py runserver
+```
+
+Or install from source:
+
+```bash
+pip install -e ".[dev]"
+cd example
+python manage.py migrate
+python manage.py runserver
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pre-commit install
+python -m pytest tests/ -q
+python manage.py shard_report   # framework size / page-load weight
+```
+
+**96 tests** with **≥90% coverage**. CI runs pre-commit, Ruff, tests (Python 3.10–3.12), and docs build on every PR.
+
+```bash
+pre-commit run --all-files  # lint + format locally
+pip install -e ".[docs]"
+python -m mkdocs serve
+```
+
+## License
+
+MIT

shrd-0.3.0/README.md

@@ -0,0 +1,96 @@
+# Shard
+
+A Django-native component framework for building UI with **props**, **server state**, **slots**, and **scoped styles** — using only the Django ecosystem plus bundled HTMX and Alpine.js.
+
+📖 **[Full documentation](https://kurtisrogers.github.io/Shard/)**
+
+Shard is a framework, not a drop-in library. Your Django project adopts its conventions: components live in your apps, templates sit beside scoped CSS, and HTMX carries server actions.
+
+## Philosophy
+
+Shard does not ship a widget catalog. It gives you a small, familiar model — closer to React/Vue than to Django templates alone — without a build step or SPA complexity:
+
+- **Props** — typed inputs declared on a Python class
+- **State** — server-owned data updated via `@action` methods
+- **Slots** — wrap and compose markup like `children` / default slots
+- **Scoped styles** — co-located `.css` files, automatically prefixed to the component
+- **Computed** — derived values via `@computed` methods
+- **Events** — HTMX custom events via `@emits` and `ActionResult`
+- **HTMX** — partial re-renders after actions
+- **Alpine.js** — optional client-side behavior inside templates
+- **View data** — optional structured layouts, mutable via `ViewTreeComponent`
+
+## Quick start
+
+```python
+# myapp/components.py
+from shard import Component, Prop, action
+
+class Card(Component):
+    title = Prop(str, default="")
+    template_name = "components/card.html"
+```
+
+```django
+{% load shard %}
+{% shard_scripts %}
+
+{% component Card title="Profile" %}
+  <p>Anything here is passed through the default slot.</p>
+{% endcomponent %}
+```
+
+See the [quickstart guide](https://kurtisrogers.github.io/Shard/getting-started/quickstart/) for a full walkthrough.
+
+## Documentation
+
+| Topic          | Link                                                                                               |
+| -------------- | -------------------------------------------------------------------------------------------------- |
+| Installation   | [getting-started/installation](https://kurtisrogers.github.io/Shard/getting-started/installation/) |
+| Components     | [concepts/components](https://kurtisrogers.github.io/Shard/concepts/components/)                   |
+| Slots          | [concepts/slots](https://kurtisrogers.github.io/Shard/concepts/slots/)                             |
+| Scoped styles  | [concepts/styles](https://kurtisrogers.github.io/Shard/concepts/styles/)                           |
+| Actions & HTMX | [interactivity/actions](https://kurtisrogers.github.io/Shard/interactivity/actions/)               |
+| HTMX & Alpine  | [guides/htmx-and-alpine](https://kurtisrogers.github.io/Shard/guides/htmx-and-alpine/)             |
+| View data      | [guides/view-data](https://kurtisrogers.github.io/Shard/guides/view-data/)                         |
+| API reference  | [reference/api](https://kurtisrogers.github.io/Shard/reference/api/)                               |
+| Examples       | [examples](https://kurtisrogers.github.io/Shard/examples/)                                         |
+
+## Example app
+
+```bash
+pip install shrd[dev]
+cd example
+python manage.py migrate
+python manage.py runserver
+```
+
+Or install from source:
+
+```bash
+pip install -e ".[dev]"
+cd example
+python manage.py migrate
+python manage.py runserver
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pre-commit install
+python -m pytest tests/ -q
+python manage.py shard_report   # framework size / page-load weight
+```
+
+**96 tests** with **≥90% coverage**. CI runs pre-commit, Ruff, tests (Python 3.10–3.12), and docs build on every PR.
+
+```bash
+pre-commit run --all-files  # lint + format locally
+pip install -e ".[docs]"
+python -m mkdocs serve
+```
+
+## License
+
+MIT

shrd-0.3.0/pyproject.toml

@@ -0,0 +1,82 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "shrd"
+version = "0.3.0"
+description = "A Django-native component framework with props, state, HTMX, and Alpine.js"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Shard Contributors" }]
+keywords = ["django", "components", "htmx", "alpine", "shard"]
+classifiers = [
+    "Framework :: Django",
+    "Framework :: Django :: 4.2",
+    "Framework :: Django :: 5.0",
+    "Framework :: Django :: 5.1",
+    "Framework :: Django :: 6.0",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Internet :: WWW/HTTP :: Dynamic Content",
+]
+dependencies = [
+    "Django>=4.2",
+]
+
+[project.urls]
+Homepage = "https://github.com/kurtisrogers/Shard"
+Documentation = "https://kurtisrogers.github.io/Shard/"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-django>=4.8",
+    "pytest-cov>=5.0",
+    "ruff>=0.9.0",
+    "pre-commit>=4.0",
+]
+docs = [
+    "mkdocs-material>=9.5",
+]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["shard*"]
+
+[tool.setuptools.package-data]
+shard = [
+    "static/**/*",
+    "templates/**/*",
+]
+
+[tool.pytest.ini_options]
+DJANGO_SETTINGS_MODULE = "tests.settings"
+pythonpath = ["."]
+testpaths = ["tests"]
+addopts = "--cov=shard --cov-report=term-missing"
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+src = ["shard", "tests", "example"]
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes
+    "I",   # isort
+    "UP",  # pyupgrade
+    "B",   # flake8-bugbear
+]
+ignore = [
+    "E501",  # line length handled by formatter
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["shard", "example", "tests"]

shrd-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

shrd-0.3.0/shard/__init__.py

@@ -0,0 +1,35 @@
+"""Shard — a Django-native component framework."""
+
+from shard.actions import ActionResult
+from shard.component import Component, action, computed, emits
+from shard.props import Prop
+from shard.render import mount, render_component
+from shard.view_data import (
+    ViewNode,
+    commit_view_tree,
+    ensure_node_ids,
+    get_slot_nodes,
+    render_view_data,
+    set_slot_nodes,
+)
+from shard.view_tree import ViewTreeComponent
+
+__all__ = [
+    "ActionResult",
+    "Component",
+    "Prop",
+    "ViewNode",
+    "ViewTreeComponent",
+    "action",
+    "commit_view_tree",
+    "computed",
+    "emits",
+    "ensure_node_ids",
+    "get_slot_nodes",
+    "mount",
+    "render_component",
+    "render_view_data",
+    "set_slot_nodes",
+]
+
+__version__ = "0.3.0"

shrd-0.3.0/shard/actions.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class ActionResult:
+    """Optional return value from an ``@action`` method.
+
+    Use when an action needs to emit HTMX events or trigger a redirect in
+    addition to updating server state.
+    """
+
+    state: dict[str, Any] | None = None
+    events: dict[str, Any] = field(default_factory=dict)
+    redirect: str | None = None
+
+    @classmethod
+    def with_events(cls, state: dict[str, Any], **events: Any) -> ActionResult:
+        return cls(state=state, events=events)

shrd-0.3.0/shard/apps.py

@@ -0,0 +1,12 @@
+from django.apps import AppConfig
+
+
+class ShardConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "shard"
+    verbose_name = "Shard Component Framework"
+
+    def ready(self) -> None:
+        from shard.registry import autodiscover_components
+
+        autodiscover_components()