fix: stop hijacking COTTON_DIR — cf-ui templates move to cotton/cf/ for consumer compatibility

Author: claude

CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## [0.1.1] — 2026-04-28
+
+### Fixed
+- **Consumer compatibility regression**: `CfUiConfig.ready()` no longer
+  overrides `settings.COTTON_DIR`. The previous fix in 0.1.0 set
+  `COTTON_DIR="cotton/bulma"` globally, which broke any consumer project
+  whose own cotton templates lived at `templates/cotton/<their-app>/...`
+  (every `<c-foo.bar>` lookup got rewritten to
+  `cotton/bulma/foo/bar/index.html` and raised `TemplateDoesNotExist`).
+
+### Changed
+- cf-ui's cotton templates moved from `cotton/<theme>/cf/*.html` to
+  `cotton/cf/*.html`. Theme variation will now happen inside the templates
+  (or via `_themes/` partials) instead of at the directory level. With the
+  default `COTTON_DIR="cotton"`, `<c-cf.foo>` continues to resolve and
+  consumer cotton trees are no longer affected.
+
+### Migration
+- Most consumers: no change required. Removing any explicit
+  `COTTON_DIR="cotton/bulma"` from `settings.py` (added as a workaround
+  while 0.1.0 was broken) is recommended.
+- If you imported `COTTON_TEMPLATES_DIR / "bulma"` directly via the escape
+  hatch, switch to `COTTON_TEMPLATES_DIR / "cf"`.
+
 ## [0.1.0] — 2026-04-25
 
 ### Added

README.md

@@ -201,10 +201,18 @@ If you need direct access to template directories for custom configuration:
 ```python
 from cf_ui import JINJA_TEMPLATES_DIR, COTTON_TEMPLATES_DIR
 
-# JINJA_TEMPLATES_DIR / "bulma"  →  Path to Jinja2 templates
-# COTTON_TEMPLATES_DIR / "bulma" →  Path to Cotton templates
+# JINJA_TEMPLATES_DIR / "bulma"  →  Path to Jinja2 templates (theme-prefixed)
+# COTTON_TEMPLATES_DIR / "cf"    →  Path to Cotton component templates
 ```
 
+> **Cotton templates are theme-agnostic on disk.** They live at
+> `cotton/cf/*.html` (not `cotton/<theme>/cf/*.html`) so cf-ui can sit
+> alongside any consumer project's own `templates/cotton/<app>/...` tree
+> without colliding on `COTTON_DIR`. The active CSS framework is selected
+> via `CF_UI_THEME` (used by the asset tags) — switching themes in a
+> future release will happen inside the templates, not via the directory
+> layout.
+
 ---
 
 ## Planned Themes

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cf-ui"
-version = "0.1.0"
+version = "0.1.1"
 description = "CSS framework UI kit for component-framework — Bulma, Bootstrap, Foundation, Fomantic, DaisyUI"
 readme = "README.md"
 requires-python = ">=3.11"

src/cf_ui/_version.py

@@ -1 +1 @@
-__version__ = "0.1.0"
+__version__ = "0.1.1"

src/cf_ui/django.py

@@ -1,30 +1,14 @@
-from pathlib import Path
-
 from django.apps import AppConfig
-from django.core.exceptions import ImproperlyConfigured
 
 
 class CfUiConfig(AppConfig):
     name = "cf_ui.django"
     label = "cf_ui"
     verbose_name = "Component Framework UI"
 
-    def ready(self) -> None:
-        from django.conf import settings
-
-        theme = getattr(settings, "CF_UI_THEME", "bulma")
-        cotton_dir = Path(__file__).parent / "templates" / "cotton" / theme
-
-        if not cotton_dir.is_dir():
-            raise ImproperlyConfigured(
-                f"cf-ui: no templates found for theme {theme!r} at {cotton_dir}. "
-                f"Check CF_UI_THEME in settings."
-            )
-
-        # django-cotton reads COTTON_DIR (singular). Setting it to
-        # "cotton/<theme>" makes <c-cf.foo> resolve to
-        # cotton/<theme>/cf/foo.html, which the cotton loader finds via
-        # the app-templates walk (cf_ui/templates/cotton/<theme>/cf/foo.html).
-        # Don't overwrite a value the consumer has already set.
-        if not getattr(settings, "COTTON_DIR", None):
-            settings.COTTON_DIR = f"cotton/{theme}"
+    # cf-ui Cotton templates live at src/cf_ui/templates/cotton/cf/*.html.
+    # Django's app-templates loader (APP_DIRS=True) picks them up directly
+    # and django-cotton's default COTTON_DIR ("cotton") resolves
+    # <c-cf.foo> -> cotton/cf/foo.html. We deliberately do not touch
+    # COTTON_DIR here: doing so would break consumer projects whose own
+    # cotton templates live at cotton/<their-app>/*.html.