bluefox-components 0.2.0__tar.gz

bluefox_components-0.2.0/.github/workflows/docs.yml

@@ -0,0 +1,13 @@
+name: Docs
+on:
+  push:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --group docs
+      - run: uv run mkdocs build

bluefox_components-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,20 @@
+name: Publish to PyPI
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

bluefox_components-0.2.0/.github/workflows/test.yml

@@ -0,0 +1,11 @@
+name: Test
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --group test
+      - run: uv run pytest tests/ -x --tb=short -q

bluefox_components-0.2.0/.gitignore

@@ -0,0 +1,207 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/

bluefox_components-0.2.0/Dockerfile.docs

@@ -0,0 +1,15 @@
+FROM python:3.12-slim AS builder
+
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+
+WORKDIR /app
+RUN uv pip install --system mkdocs-material mkdocs-minify-plugin
+
+COPY mkdocs.yml ./
+COPY docs/ docs/
+RUN mkdocs build
+
+FROM nginx:alpine
+COPY landing/ /usr/share/nginx/html/
+COPY --from=builder /app/site /usr/share/nginx/html/docs/
+EXPOSE 80

bluefox_components-0.2.0/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,264 @@
+# bluefox-components — Implementation Plan
+
+> A lightweight design system for the Bluefox Stack. Jinja2 macros, Pico CSS theming, and a built-in component showcase.
+
+## What it is
+
+A PyPI package (`uv add bluefox-components`) that provides:
+
+1. **Jinja2 macro templates** — parameterized, composable UI building blocks under the `bfx/` namespace
+2. **A CSS file** (`bluefox.css`) — Pico CSS variable overrides for the Bluefox default theme
+3. **A FastAPI router** — mountable at `/components` (auth-protected) for a storybook-like component showcase
+4. **A setup function** — registers the package's template directory with Jinja2 and mounts static files
+
+## Design decisions
+
+- **Macros, not includes.** Every component is a Jinja2 macro with explicit parameters. Apps consume them via `{% from "bfx/button.html" import button %}`. This gives composability and parameterization without a build step.
+- **Pure Pico CSS + variable overrides.** No Tailwind, no custom utility classes. `bluefox.css` only sets CSS custom properties (`--pico-primary-*`, `--pico-border-radius`, font stacks). Pico's semantic HTML approach means most components need zero custom CSS.
+- **Production route.** The `/components` showcase is a real route, not dev-only. Protected by auth so only logged-in users (or admins) can access it. Useful as living documentation for the team building on the stack.
+- **Auth pages live in bluefox-framework.** The `bluefox-auth` package provides the auth logic (JWT, users, permissions). The actual login/register/forgot-password *templates* live in the framework layer and import macros from `bluefox-components`. This keeps `bluefox-auth` focused on backend concerns.
+
+## Dependency chain
+
+```
+bluefox-core  ←  bluefox-components  ←  bluefox-auth (logic only)
+                                      ←  bluefox-framework (auth pages + app templates)
+                                      ←  your app modules
+```
+
+## Package structure
+
+```
+bluefox-components/
+├── src/bluefox_components/
+│   ├── __init__.py              # setup_components(app), component_router
+│   ├── router.py                # FastAPI router for /components showcase
+│   ├── templates/
+│   │   ├── bfx/                 # namespace — apps import from "bfx/..."
+│   │   │   ├── base.html        # base layout (html, head, body, nav, footer)
+│   │   │   ├── button.html      # {% macro button(label, variant, ...) %}
+│   │   │   ├── input.html       # {% macro input(name, type, label, ...) %}
+│   │   │   ├── select.html      # {% macro select(name, options, ...) %}
+│   │   │   ├── textarea.html    # {% macro textarea(name, label, ...) %}
+│   │   │   ├── card.html        # {% macro card(title, footer) %}...caller...{% endmacro %}
+│   │   │   ├── alert.html       # {% macro alert(message, variant) %}
+│   │   │   ├── modal.html       # {% macro modal(id, title) %}
+│   │   │   ├── nav.html         # {% macro nav(brand, items, user) %}
+│   │   │   ├── table.html       # {% macro data_table(headers, rows) %}
+│   │   │   ├── pagination.html  # {% macro pagination(page, total_pages, url) %}
+│   │   │   ├── form.html        # {% macro form_group(label, error) %}, csrf helpers
+│   │   │   └── loading.html     # {% macro loading_spinner() %}, HTMX indicators
+│   │   └── bfx_preview/         # templates for the showcase UI itself
+│   │       ├── layout.html
+│   │       └── showcase.html
+│   └── static/
+│       └── bfx/
+│           └── bluefox.css      # Pico CSS variable overrides only
+├── tests/
+│   ├── conftest.py
+│   └── test_components.py       # template rendering tests
+├── pyproject.toml
+└── README.md
+```
+
+## Integration
+
+### App factory
+
+```python
+from bluefox_components import setup_components, component_router
+
+app = create_bluefox_app(settings)
+setup_components(app)
+
+# Auth-protected showcase route
+app.include_router(component_router, prefix="/components", tags=["components"])
+```
+
+### Template usage
+
+```jinja2
+{% extends "bfx/base.html" %}
+{% from "bfx/button.html" import button %}
+{% from "bfx/input.html" import input %}
+{% from "bfx/form.html" import form_group, form_group_end %}
+
+{% block content %}
+<article>
+  <h2>Login</h2>
+  <form method="post" action="/auth/login">
+    {% call form_group("Email", error=errors.get("email")) %}
+      {{ input(name="email", type="email", required=true) }}
+    {% endcall %}
+    {% call form_group("Password", error=errors.get("password")) %}
+      {{ input(name="password", type="password", required=true) }}
+    {% endcall %}
+    {{ button("Sign in") }}
+  </form>
+</article>
+{% endblock %}
+```
+
+---
+
+## Phases
+
+### Phase 1 — Foundation
+
+**Goal:** Installable package that registers templates and serves a base layout with the Bluefox theme.
+
+| Step | Description |
+|------|-------------|
+| 1.1 | Project scaffold — `pyproject.toml` with `bluefox-core` dependency, src layout, uv workspace |
+| 1.2 | `setup_components(app)` — adds the package's `templates/` directory to Jinja2's loader, mounts `/static/bfx/` for the CSS file. Single function call, follows the `BluefoxAuth(app)` pattern |
+| 1.3 | `bfx/base.html` — base layout template. `<html>`, Pico CSS CDN link, `bluefox.css` link, `<nav>` block, `<main>` with `{% block content %}`, `<footer>`. Every Bluefox app extends this |
+| 1.4 | `bluefox.css` — CSS variable overrides only. Bluefox color palette, border-radius, font choices. No component-specific CSS, no utility classes. Just the theme on top of Pico |
+| 1.5 | Tests — template rendering tests using `bluefox-test`. Verify base layout renders, static files mount correctly |
+
+**Done when:** `uv add bluefox-components`, call `setup_components(app)`, extend `bfx/base.html` from an app template, and see the Bluefox-themed page.
+
+### Phase 2 — Core macros
+
+**Goal:** The macros needed to build auth pages and basic CRUD forms.
+
+| Step | Description |
+|------|-------------|
+| 2.1 | **Form macros** — `input(name, type, label, placeholder, error, required, **attrs)`, `select(name, options, label, error, **attrs)`, `textarea(name, label, error, **attrs)`. The `**attrs` dict passes through as HTML attributes, enabling HTMX (`hx-post`, `hx-target`, etc.) without the macro needing to know about HTMX |
+| 2.2 | **Form group** — `form_group(label, error)` as a `{% call %}` macro that wraps a label + input + error message. Keeps the label/error/input association consistent across all forms |
+| 2.3 | **Button** — `button(label, variant="primary", type="submit", **attrs)`. Variants map to Pico's existing classes: `primary` (default), `secondary`, `outline`, `contrast`. Supports `role="button"` on `<a>` tags via an `href` parameter |
+| 2.4 | **Alert** — `alert(message, variant="info", dismissible=false)`. For flash messages, form errors, success notifications. Variants: `info`, `success`, `warning`, `error` |
+| 2.5 | **Card** — `{% call card(title="...", footer="...") %}content{% endcall %}`. Uses Pico's `<article>` with `<header>` and `<footer>` |
+| 2.6 | **Nav** — `nav(brand, items, user)`. Renders the standard Bluefox nav with logo/brand, navigation links, and auth-aware user section (login/register or user dropdown) |
+| 2.7 | Tests — each macro rendered with various parameter combinations, output validated for correct HTML structure and Pico classes |
+
+**Done when:** Auth pages (login, register, forgot-password) can be built entirely from these macros with zero custom HTML for form elements.
+
+### Phase 3 — Component showcase
+
+**Goal:** A production route at `/components` that displays every macro with live examples and copy-paste code.
+
+| Step | Description |
+|------|-------------|
+| 3.1 | `component_router` — FastAPI `APIRouter` with auth dependency. Single page that renders the full showcase |
+| 3.2 | Showcase layout — a clean page (extends `bfx/base.html`) with a sidebar listing all components and a main area showing each one |
+| 3.3 | Component sections — for each macro, render it in multiple states: default, each variant, disabled, with error, with HTMX attributes. Group by category (forms, layout, feedback, navigation) |
+| 3.4 | Source preview — next to each rendered component, show the Jinja2 macro call that produces it. Developers copy-paste from here. Rendered in a `<pre><code>` block |
+
+**Done when:** Visit `/components` in any Bluefox app and see every available macro with examples and usage code.
+
+### Phase 4 — Extended components
+
+**Goal:** Additional macros for building full application pages. Built as real pages need them (YAGNI).
+
+| Step | Description |
+|------|-------------|
+| 4.1 | **Data table** — `data_table(headers, rows, empty_message)` with optional sort indicators, empty state |
+| 4.2 | **Pagination** — `pagination(page, total_pages, base_url)` with HTMX-powered page navigation |
+| 4.3 | **Modal** — `modal(id, title)` using the `<dialog>` element, toggleable via HTMX or minimal inline JS |
+| 4.4 | **Loading indicators** — `loading_spinner()` and `loading_skeleton(lines)`, compatible with `hx-indicator` |
+| 4.5 | **Empty state** — `empty_state(message, action_label, action_url)` for when lists have no items |
+| 4.6 | **Breadcrumbs** — `breadcrumbs(items)` for page hierarchy navigation |
+| 4.7 | **Badge** — `badge(label, variant)` for status indicators, counts, tags |
+| 4.8 | Update showcase with all new components |
+
+**Done when:** A full CRUD module (list → detail → create → edit → delete) can be built entirely from macros.
+
+### Phase 5 — Theme variants (future)
+
+**Goal:** Alternate visual identities for different app personalities, switchable via a single CSS variable or attribute.
+
+| Step | Description |
+|------|-------------|
+| 5.1 | Named themes — alternate sets of CSS variables for different feels: `financial` (conservative, serif), `playful` (rounded, colorful), `minimal` (monochrome, tight spacing). Applied via `data-bfx-theme="financial"` on `<html>` |
+| 5.2 | Theme file structure — each theme is a separate CSS file (`bluefox-financial.css`, etc.) that overrides the same Pico variables as `bluefox.css` |
+| 5.3 | Theme toggle in showcase — extend the `/components` page with a theme switcher to preview all components under each theme |
+| 5.4 | Custom theme guide — documentation on how to create your own theme file by overriding the CSS variables |
+
+**Done when:** Changing one line (the theme attribute or CSS import) gives an app a completely different visual identity while keeping all macros unchanged.
+
+---
+
+## Macro API conventions
+
+All macros follow these conventions:
+
+1. **Explicit parameters for common use cases.** `button(label, variant="primary", type="submit")` — the 90% case is covered by named parameters.
+2. **`**attrs` dict for escape hatches.** Every macro accepts an `attrs` parameter (a dict) that gets rendered as HTML attributes. This is how HTMX, Alpine.js, `data-*`, and `aria-*` attributes pass through without the macro needing to enumerate them.
+3. **Pico-native HTML.** Macros emit semantic HTML that Pico already styles. A `card` is an `<article>`, a `form_group` is a `<label>` wrapping an input, a `nav` is a `<nav>` with `<ul>`. Minimal custom classes.
+4. **`{% call %}` for content slots.** Components that wrap arbitrary content (card, modal, form_group) use Jinja2's caller convention: `{% call card(title="...") %}your content{% endcall %}`.
+5. **No JavaScript by default.** Macros produce static HTML. HTMX attributes are passed via `attrs`. The only exception is `modal` which may include a minimal inline script for `<dialog>` show/close.
+
+### Example macro implementation
+
+```jinja2
+{# bfx/button.html #}
+
+{% macro button(label, variant="primary", type="submit", href=none, disabled=false, attrs={}) %}
+{% if href %}
+<a href="{{ href }}" role="button"
+  {% if variant != "primary" %}class="{{ variant }}"{% endif %}
+  {% if disabled %}aria-disabled="true"{% endif %}
+  {% for key, val in attrs.items() %}{{ key }}="{{ val }}"{% endfor %}
+>{{ label }}</a>
+{% else %}
+<button type="{{ type }}"
+  {% if variant != "primary" %}class="{{ variant }}"{% endif %}
+  {% if disabled %}disabled{% endif %}
+  {% for key, val in attrs.items() %}{{ key }}="{{ val }}"{% endfor %}
+>{{ label }}</button>
+{% endif %}
+{% endmacro %}
+```
+
+Usage:
+
+```jinja2
+{% from "bfx/button.html" import button %}
+
+{{ button("Save") }}
+{{ button("Cancel", variant="secondary", href="/dashboard") }}
+{{ button("Delete", variant="outline", attrs={"hx-delete": "/items/1", "hx-confirm": "Are you sure?"}) }}
+{{ button("Processing...", disabled=true) }}
+```
+
+---
+
+## CSS variable strategy
+
+`bluefox.css` overrides Pico's CSS custom properties. No custom classes, no `!important`, no component-scoped styles.
+
+```css
+/* bluefox.css — theme layer on top of Pico CSS */
+
+:root {
+  /* Brand colors */
+  --pico-primary: #3b82f6;
+  --pico-primary-hover: #2563eb;
+  --pico-primary-focus: rgba(59, 130, 246, 0.25);
+  --pico-primary-inverse: #fff;
+
+  /* Typography */
+  --pico-font-family: system-ui, -apple-system, "Segoe UI", "Roboto", "Helvetica Neue", sans-serif;
+  --pico-font-size: 100%;
+  --pico-line-height: 1.5;
+
+  /* Border radius */
+  --pico-border-radius: 0.375rem;
+
+  /* Spacing adjustments (if any) */
+}
+
+/* Dark mode overrides (Pico supports data-theme="dark") */
+[data-theme="dark"] {
+  --pico-primary: #60a5fa;
+  --pico-primary-hover: #93bbfd;
+}
+```
+
+The exact values will be derived from the current bluefox-stack website's color palette to ensure visual consistency across all Bluefox properties.
+
+---
+
+## Build order recommendation
+
+**Build Phases 1 → 2 first.** That unblocks auth page templates in `bluefox-framework`. Phase 3 (showcase) comes immediately after as a quality-of-life tool. Phase 4 components get added as real app pages demand them. Phase 5 is explicitly "later — only if we want it."

bluefox_components-0.2.0/Makefile

@@ -0,0 +1,29 @@
+.PHONY: dev test test-fast docs docs-build landing clean
+
+# Serve landing page on :8090 and docs on :8000
+dev:
+	python -m http.server 8090 --directory landing & uv run mkdocs serve
+
+# Run all tests
+test:
+	uv run pytest tests/ -v --tb=short
+
+# Run tests quickly (stop on first failure)
+test-fast:
+	uv run pytest tests/ -x --tb=short -q
+
+# Serve docs locally (MkDocs)
+docs:
+	uv run mkdocs serve
+
+# Build docs to site/
+docs-build:
+	uv run mkdocs build
+
+# Serve landing page locally
+landing:
+	python -m http.server 8090 --directory landing
+
+# Remove build artifacts
+clean:
+	rm -rf site/ dist/ *.egg-info .pytest_cache

bluefox_components-0.2.0/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: bluefox-components
+Version: 0.2.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.

bluefox_components-0.2.0/README.md

@@ -0,0 +1,3 @@
+# bluefox-components
+
+Jinja2 macro components and Pico CSS theming for the Bluefox Stack.

bluefox_components-0.2.0/bluefox_components/__init__.py

@@ -0,0 +1,5 @@
+from bluefox_components.setup import setup_components
+
+__all__ = [
+    "setup_components",
+]

bluefox_components-0.2.0/bluefox_components/setup.py

@@ -0,0 +1,34 @@
+"""Register bluefox-components templates and static files with a FastAPI app."""
+
+from pathlib import Path
+
+from fastapi import FastAPI
+from fastapi.staticfiles import StaticFiles
+
+from bluefox_core.templates import add_template_directory
+
+
+_PKG_DIR = Path(__file__).parent
+
+
+def setup_components(app: FastAPI) -> None:
+    """Register the component templates and mount static assets.
+
+    Call this once during app startup::
+
+        from bluefox_components import setup_components
+        setup_components(app)
+    """
+    # Register bfx/ templates so apps can {% extends "bfx/base.html" %}
+    add_template_directory(app, _PKG_DIR / "templates")
+
+    # Mount the CSS theme file at /static/bfx/ (guard against duplicate mounts)
+    already_mounted = any(
+        getattr(r, "path", None) == "/static/bfx" for r in app.routes
+    )
+    if not already_mounted:
+        app.mount(
+            "/static/bfx",
+            StaticFiles(directory=str(_PKG_DIR / "static" / "bfx")),
+            name="bfx-static",
+        )