Skip to content

Releases: fsecada01/component-framework-ui

v0.1.0 — Bulma theme, 14 components, three-tier test suite

26 Apr 01:51
@fsecada01 fsecada01
v0.1.0
7adc77b

Choose a tag to compare

View all tags
v0.1.0 — Bulma theme, 14 components, three-tier test suite Latest
Latest

What is cf-ui?

component-framework-ui is the official UI kit layer for component-framework. It ships ready-to-use component templates in two first-class template sets — Jinja2/JinjaX (FastAPI, Litestar) and django-cotton (Django) — so consuming apps code against <CfCard> and <c-cf.card>, not against a specific CSS framework.

Switching themes means changing one config line. Zero template changes across the codebase.

Installation

pip install "cf-ui[bulma]"
# Django — settings.py
INSTALLED_APPS = [..., "cf_ui.django.CfUiConfig"]
CF_UI_THEME = "bulma"
TEMPLATES = [{"OPTIONS": {"libraries": {"cf_ui": "cf_ui.templatetags.cf_ui"}}}]

# FastAPI
from cf_ui.fastapi import install_cf_ui
install_cf_ui(catalog, theme="bulma")

# Litestar
from cf_ui.litestar import install_cf_ui
install_cf_ui(config, theme="bulma")

What's included

14 Bulma components

Forms — direct integration with component-framework's FormComponent state/errors lifecycle:

Component Props
CfFormField / <c-cf.form-field> name, label, value, error, type, required, extra_class, input_class
CfSelect / <c-cf.select> name, label, value, error, options, extra_class, input_class
CfTextarea / <c-cf.textarea> name, label, value, error, rows, extra_class, input_class
CfCheckboxGroup / <c-cf.checkbox-group> name, label, choices, selected, error, extra_class, control_class

Feedback — HTMX swap targets and Alpine.js-driven interactivity:

Component Props / Slots
CfModal / <c-cf.modal> id, extra_class; slots: header, body, footer
CfNotification / <c-cf.notification> message, type, dismissible
CfProgress / <c-cf.progress> value, max, type, label — SSE streaming target

Content:

Component Props / Slots
CfCard / <c-cf.card> extra_class; slots: header, body, footer
CfTable / <c-cf.table> columns, rows, hx_target, hx_url
CfPagination / <c-cf.pagination> page, total_pages, hx_target, hx_url
CfPanel / <c-cf.panel> title, open, extra_class; slot: body

Navigation:

Component Props / Slots
CfNavbar / <c-cf.navbar> extra_class; slots: brand, start, end
CfBreadcrumb / <c-cf.breadcrumb> items (list of {label, url})
CfTabs / <c-cf.tabs> tabs (list of {id, url}), hx_target

CDN asset tags

{% load cf_ui %}
{% cf_ui_head %}  {# Bulma CSS + x-cloak style #}
{% cf_ui_body %}  {# cf_ui_alpine.js + Alpine CDN, both deferred #}

Version overrides via CF_UI_CDN_VERSIONS. Opt out entirely by not calling the tags.

Alpine.js integration (cf_ui_alpine.js)

Loaded by {% cf_ui_body %} — registers named Alpine components and a global store:

{# Named components — bind from outside the element #}
<div x-data="cfModal">...</div>

{# $cf global store — cross-component messaging from any template #}
<button @click="Alpine.store('cf').notify('Saved!', 'success')">Save</button>
<button @click="Alpine.store('cf').modal.open('confirm')">Delete</button>

Modal control uses cf-modal-open / cf-modal-close custom events — no private Alpine API access.

Test coverage

Tier Count Description
Unit 114 Jinja2 Environment + render_to_string, no browser
Integration 8 FastAPI TestClient + Django test Client, real HTTP
E2E 17 Playwright, js_on + js_off parameterized
Total 139 1 intentionally skipped (js_off-only accessibility check)

CI runs on Python 3.11, 3.12, and 3.13.

Migration

A migration prompt for Django projects is available at prompts/migrate-django.md. Load it into your Claude Code session to get a phase-by-phase migration plan tailored to your project.

Theme roadmap

Theme Status
Bulma ✅ This release
Bootstrap 📋 Planned
Foundation 📋 Planned
Fomantic UI 📋 Planned
Tailwind + DaisyUI 📋 Planned

Stub directories for all planned themes ship in v0.1.0 — the directory contract is established so adding a new theme is a pure addition with no breaking changes.

Known requirements

  • component-framework >= 0.4 — not yet on PyPI; install from GitHub: pip install "git+https://github.com/fsecada01/component-framework.git"
  • django-cotton 2.x — uses <c-vars> (not <c-props>)
  • JinjaX 0.41+ — uses add_folder() (not add_path()); class is reserved in {#def} headers, use extra_class
  • Alpine.js 3.x required when using {% cf_ui_body %}
Assets 2
Loading