Metadata-Version: 2.4
Name: bluefox-components
Version: 0.9.0
Summary: Jinja2 macro components and Pico CSS theming for the Bluefox Stack.
Project-URL: Homepage, https://bluefox-components.bluefox.software
Project-URL: Repository, https://github.com/blue-fox-software/bluefox-components
License-Expression: MIT
Requires-Python: >=3.12
Requires-Dist: bluefox-core>=0.4.0
Description-Content-Type: text/markdown

# bluefox-components

Jinja2 macro components and Pico CSS theming for the [Bluefox Stack](https://bluefox-stack.bluefox.software).

## What it is

A PyPI package that provides:

- **Jinja2 macro templates** — parameterized, composable UI building blocks under the `bfx/` namespace
- **A CSS theme layer** — Pico CSS variable overrides for the Bluefox default palette, plus 4 alternate theme variants
- **A component showcase** — mountable FastAPI router for a storybook-like preview of every component
- **A setup function** — registers templates and static assets with one call

## Quick start

```bash
uv add bluefox-components
```

```python
from bluefox_core import BluefoxSettings, create_bluefox_app
from bluefox_components import setup_components

settings = BluefoxSettings()
app = create_bluefox_app(settings)
setup_components(app)
```

```jinja2
{% extends "bfx/base.html" %}
{% from "bfx/button.html" import button %}
{% from "bfx/input.html" import input %}

{% block content %}
<form method="post">
  {{ input("email", type="email", label="Email") }}
  {{ button("Sign in") }}
</form>
{% endblock %}
```

## Components

| Category | Macros |
|----------|--------|
| **Forms** | `button`, `input`, `select`, `textarea`, `form_group`, `csrf_input` |
| **Layout** | `card`, `nav`, `breadcrumbs` |
| **Data** | `data_table`, `pagination`, `empty_state` |
| **Feedback** | `alert`, `badge`, `modal`, `modal_trigger`, `loading_spinner`, `loading_skeleton` |

Every macro accepts an `attrs` parameter (dict) for arbitrary HTML attributes — HTMX, Alpine.js, `data-*`, `aria-*` all pass through without the macro needing to know about them.

## Themes

4 theme variants, each with distinct typography, border radii, and visual identity:

| Theme | Font | Feel |
|-------|------|------|
| **Financial** | Inter + DM Serif Display | Corporate, conservative, tight corners |
| **Playful** | Nunito | Bouncy, pill buttons, purple accent |
| **Minimal** | IBM Plex Sans | Monochrome, zero radius, dense |
| **Roommate** | Outfit + DM Serif Display | Warm terracotta, soft rounded |

Apply a theme with a single attribute on `<html>`:

```html
<html data-bfx-theme="financial">
```

Or pass it from your template:

```jinja2
{% extends "bfx/base.html" %}
{# renders: <html data-bfx-theme="financial"> #}
```

```python
templates.get_template("page.html").render(theme="financial")
```

## Component showcase

Mount the built-in showcase router for live documentation:

```python
from bluefox_components import component_router

app.include_router(component_router, prefix="/components")
```

## Design decisions

- **Macros, not includes.** Explicit parameters for the 90% case, `attrs` dict for escape hatches.
- **Pure Pico CSS.** No Tailwind, no utility classes. Themes override CSS custom properties only.
- **Zero build step.** No bundler, no compilation. Install, call `setup_components()`, use macros.
- **Semantic HTML.** A card is an `<article>`, a form group is a `<label>`, a nav is a `<nav>`. Pico styles them automatically.

## Requirements

- Python >= 3.12
- [bluefox-core](https://pypi.org/project/bluefox-core/) >= 0.4.0

## License

MIT
