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
