Files
phelex 0d171915d7 Add Site Studio themes and Theme Manager
Support categorized fragments, theme presets, block widths, and server-backed theme editing with onboarding and preview.

Include Site Studio, design sources, specification and verification reports; remove the legacy studio-site example.
2026-11-13 14:04:49 +03:00

264 lines
15 KiB
Python

"""File theme validation, shared CSS and immutable releases without editable examples."""
import datetime as dt
import json
import os
import tempfile
import unittest
from pathlib import Path
from unittest.mock import patch
from theme_fixture import document, seed, write
from site_engine.build.pipeline import build_site, preview_page
from site_engine.core.registry import load_site
from site_engine.core.theme import default_theme, preset_catalog, resolve_theme, theme_css
from site_engine.core.validate import validate_workspace
from site_engine.errors import EngineError, Report
from site_engine.parsing.yamlio import dump_yaml
from site_engine.services.publish import rollback
NOW = dt.datetime(2026, 11, 13, 12, tzinfo=dt.UTC)
class ThemeTest(unittest.TestCase):
def resolve(self, overrides=None, preset="minimal"):
report = Report()
result = resolve_theme(document(preset, overrides), report)
return result, report
def test_exact_design_presets_and_independent_catalog_copies(self):
expected = {"minimal": ("#4255b9", 1180), "dark": ("#a48bfa", 1240),
"editorial": ("#82563e", 1040), "bold": ("#df466f", 1280),
"natural": ("#49775c", 1140), "custom": ("#6554ce", 1180)}
for name, (color, width) in expected.items():
with self.subTest(name=name):
overrides = {k: v for k, v in preset_catalog()[name].items() if k in ("colors", "type", "ui")} if name == "custom" else {}
theme, report = self.resolve(overrides, name)
self.assertTrue(report.ok, report.issues)
self.assertEqual(theme.tokens["colors"]["primary"], color)
self.assertEqual(theme.container.max_width, width)
catalog = preset_catalog()
catalog["dark"]["colors"]["primary"] = "modified"
self.assertEqual(preset_catalog()["dark"]["colors"]["primary"], "#a48bfa")
def test_deep_overrides_preserve_other_tokens(self):
theme, report = self.resolve({"colors": {"primary": "#123456"}, "ui": {"container": {"mode": "fluid", "gutter": {"mobile": 0}}}})
self.assertTrue(report.ok, report.issues)
self.assertEqual(theme.container.gutter.desktop, 32)
self.assertEqual(theme.container.gutter.mobile, 0)
self.assertEqual(theme.container.mode, "fluid")
self.assertEqual(theme.tokens["colors"]["surface"], "#ffffff")
self.assertIn("--color-primary: #123456;", theme_css(theme))
def test_custom_requires_complete_groups(self):
theme, report = self.resolve({"colors": {"primary": "#123456"}}, "custom")
self.assertIsNone(theme)
self.assertIn("E_THEME_CUSTOM", report.codes())
values = {k: v for k, v in preset_catalog()["custom"].items() if k in ("colors", "type", "ui")}
del values["ui"]["container"]["gutter"]["mobile"]
self.assertIn("E_THEME_CUSTOM", self.resolve(values, "custom")[1].codes())
def test_invalid_document_versions_and_unknown_keys(self):
for values in ({"schema": True}, {"schema": 2}, {"preset": []}, {"preset": "missing"},
{"preset_version": True}, {"preset_version": 2}, {"inline": {}}, {"overrides": None}):
with self.subTest(values=values):
report = Report()
self.assertIsNone(resolve_theme({**document(), **values}, report))
self.assertFalse(report.ok)
def test_invalid_group_shapes_report_instead_of_crashing(self):
for group in ("colors", "type", "ui", "custom_colors", "gradients"):
for value in (None, False, 0, [], "url(https://invalid)"):
with self.subTest(group=group, value=value):
theme, report = self.resolve({group: value})
self.assertIsNone(theme)
self.assertTrue(any(i.path.startswith("theme.yaml.overrides." + group) for i in report.errors))
def test_numeric_boundaries_and_strict_types(self):
for group, key, valid, invalid in (
("type", "scale", [.85, 1.3], [.84, 1.31, True, "1", float("nan"), float("inf"), 10**1000]),
("type", "line", [1.3, 1.9], [1.29, 1.91, None]),
("type", "headingWeight", [100, 900], [99, 901, 700.0, True]),
("ui", "radius", [0, 24], [-1, 25, "8px"]),
("ui", "spacing", [.8, 1.4], [.79, 1.41, False]),
):
for value in valid + invalid:
with self.subTest(group=group, key=key, value=value):
theme, report = self.resolve({group: {key: value}})
self.assertEqual(theme is not None, value in valid and type(value) is not bool)
self.assertEqual(report.ok, theme is not None)
def test_container_types_ranges_keys_and_legacy_numeric(self):
invalid = [1080, None, [], {"mode": "wide"}, {"mode": []}, {"max_width": 719},
{"max_width": 1921}, {"max_width": 1080.0}, {"max_width": True},
{"gutter": []}, {"gutter": {"mobile": -1}}, {"gutter": {"desktop": 97}},
{"gutter": {"tablet": "24"}}, {"gutter": {"phone": 16}}, {"width": 1200}]
for cn in invalid:
with self.subTest(container=cn):
theme, report = self.resolve({"ui": {"container": cn}})
self.assertIsNone(theme)
self.assertFalse(report.ok)
for mode in ("boxed", "fluid", "full"):
for width in (720, 1920):
theme, report = self.resolve({"ui": {"container": {"mode": mode, "max_width": width, "gutter": {"mobile": 0, "desktop": 96}}}})
self.assertTrue(report.ok)
self.assertEqual(theme.container.max_width, width)
def test_css_url_script_jinja_and_unapproved_font_are_rejected(self):
for override in (
{"colors": {"primary": "red; }body{display:none}"}},
{"colors": {"surface": "#fff"}}, {"colors": {"accent": "{{ x }}"}},
{"type": {"body": "url(https://example.org/font)"}},
{"type": {"heading": "</style><script>1</script>"}},
{"type": {"pair": "unknown"}}, {"ui": {"shadow": "anything"}},
{"ui": {"button": "gradient"}}, {"ui": {"css": "color:red"}},
):
with self.subTest(override=override):
theme, report = self.resolve(override)
self.assertIsNone(theme)
self.assertFalse(report.ok)
def test_named_colors_limits_and_reserved_names(self):
valid = {f"brand_{i}": "#123456" for i in range(24)}
theme, report = self.resolve({"custom_colors": valid})
self.assertTrue(report.ok)
self.assertIn("--color-brand-0: #123456", theme_css(theme))
for extra in ({**valid, "another": "#123456"}, {"primary": "#123456"},
{"a": "#123456"}, {"Bad_Name": "#123456"}, {"font;body": "#123456"},
{"brand": "url(x)"}, {1: "#123456"}):
with self.subTest(extra=extra):
self.assertFalse(self.resolve({"custom_colors": extra})[1].ok)
def test_gradients_validate_all_stops_and_disable_with_solid_fallback(self):
definition = {"type": "linear", "angle": 145, "stops": [{"at": 0, "color": "#112233"}, {"at": 55, "color": "#445566"}, {"at": 100, "color": "#778899"}]}
theme, report = self.resolve({"gradients": {"enabled": True, "definitions": {"hero": definition}}})
self.assertTrue(report.ok)
self.assertIn("W_THEME_GRADIENT_CONTRAST", report.codes())
self.assertIn("--hero-gradient: linear-gradient(145deg, #112233 0%, #445566 55%, #778899 100%);", theme_css(theme))
theme, _ = self.resolve({"gradients": {"enabled": False, "definitions": {"hero": definition}}})
self.assertNotIn("linear-gradient", theme_css(theme))
self.assertIn("--hero-gradient: #4255b9", theme_css(theme))
for key, value in (("type", "radial"), ("angle", -1), ("angle", 361), ("angle", True),
("stops", []), ("stops", [{"at": 0, "color": "#fff"}] * 2),
("stops", [{"at": 20, "color": "#112233"}, {"at": 20, "color": "#445566"}]),
("stops", [{"at": "0", "color": "#112233"}, {"at": 100, "color": "#445566"}])):
with self.subTest(key=key, value=value):
self.assertFalse(self.resolve({"gradients": {"definitions": {"hero": {**definition, key: value}}}})[1].ok)
self.assertFalse(self.resolve({"gradients": {"enabled": "true"}})[1].ok)
self.assertFalse(self.resolve({"gradients": {"definitions": {f"gradient_{i}": definition for i in range(13)}}})[1].ok)
def test_contrast_is_warning_and_defaults_have_no_gradients(self):
theme, report = self.resolve({"colors": {"text": "#ffffff", "muted": "#ffffff", "surface": "#ffffff", "background": "#ffffff"}})
self.assertIsNotNone(theme)
self.assertTrue(report.ok)
self.assertEqual(len(report.warnings), 3)
self.assertFalse(default_theme().tokens["gradients"]["enabled"])
class ThemeReleaseTest(unittest.TestCase):
def setUp(self):
temp = tempfile.TemporaryDirectory()
self.addCleanup(temp.cleanup)
self.work = Path(temp.name)
self.site, self.out = self.work / "site", self.work / "dist"
seed(self.site)
def test_no_theme_uses_safe_default_without_creating_file(self):
write(self.site, "site.yaml", "name: New site\n")
(self.site / "theme.yaml").unlink()
reg = load_site(self.site)
self.assertTrue(reg.report.ok)
self.assertEqual(reg.theme.document.preset, "minimal")
self.assertFalse((self.site / "theme.yaml").exists())
def test_bad_explicit_file_inline_config_and_malformed_yaml(self):
configs = [{"file": "missing.yaml"}, {"file": "../secret.yaml"}, {"file": "/tmp/secret"},
{"file": None}, {"file": ""}, {"tokens": {"color.primary": "#123456"}}, [], False]
for config in configs:
with self.subTest(config=config):
write(self.site, "site.yaml", dump_yaml({"name": "Invalid theme", "theme": config}))
self.assertFalse(load_site(self.site).report.ok)
write(self.site, "site.yaml", dump_yaml({"name": "Invalid theme", "theme": {"file": "theme.yaml"}}))
for text in ("[", "", "schema: 1\nschema: 1", "schema: 1\npreset: &x minimal\npreset_version: *x", "- item"):
with self.subTest(text=text):
write(self.site, "theme.yaml", text)
self.assertFalse(load_site(self.site).report.ok)
def test_theme_symlink_cannot_escape_site_root(self):
write(self.work, "outside.yaml", dump_yaml(document()))
(self.site / "theme.yaml").unlink()
(self.site / "theme.yaml").symlink_to(self.work / "outside.yaml")
self.assertIn("E_THEME_FILE", load_site(self.site).report.codes())
def test_all_presets_build_and_manifest_pins_effective_tokens(self):
for preset in preset_catalog():
with self.subTest(preset=preset):
overrides = {k: v for k, v in preset_catalog()[preset].items() if k in ("colors", "type", "ui")} if preset == "custom" else {}
write(self.site, "theme.yaml", dump_yaml(document(preset, overrides)))
result = build_site(self.site, self.out, now=NOW, keep=10)
manifest = json.loads((result.output_dir / "manifest.json").read_text())
self.assertEqual(manifest["theme"]["document"]["preset"], preset)
self.assertEqual(manifest["theme"]["document"]["preset_version"], 1)
self.assertTrue(manifest["render_hash"])
css = next((result.output_dir / "assets").glob("site.*.css")).read_text()
expected = manifest["theme"]["effective_tokens"]["colors"]["primary"]
self.assertIn("--color-primary: " + expected, css)
self.assertNotIn("data-preview-", (result.output_dir / "index.html").read_text())
def test_public_and_passive_preview_share_css_and_override_defaults_last(self):
result = build_site(self.site, self.out, now=NOW)
css = next((result.output_dir / "assets").glob("site.*.css")).read_text()
html, report = preview_page(self.site, "index", now=NOW)
self.assertTrue(report.ok, report.issues)
self.assertIn(css, html)
self.assertGreater(css.index("--color-primary:"), css.index("/* fragment: hero */"))
def test_contrast_warning_does_not_block_release(self):
write(self.site, "theme.yaml", dump_yaml(document(overrides={"colors": {"text": "#ffffff"}})))
result = build_site(self.site, self.out, now=NOW)
self.assertIn("W_THEME_CONTRAST", result.report.codes())
self.assertTrue(result.report.ok)
def test_invalid_theme_preserves_live_and_is_visible_to_preview(self):
original = build_site(self.site, self.out, now=NOW)
write(self.site, "theme.yaml", dump_yaml(document(overrides={"ui": {"container": 1080}})))
self.assertIn("E_THEME_SHAPE", validate_workspace(load_site(self.site)).codes())
for action in (lambda: build_site(self.site, self.out, now=NOW), lambda: preview_page(self.site, "index")):
with self.assertRaises(EngineError) as caught:
action()
self.assertIn("E_THEME_SHAPE", caught.exception.report.codes())
self.assertEqual(os.readlink(self.out / "current"), original.build_id)
def test_reproducibility_and_rollback_do_not_change_workspace(self):
first = build_site(self.site, self.out, now=NOW)
original_bytes = (first.output_dir / "manifest.json").read_bytes()
again = build_site(self.site, self.out, now=NOW)
self.assertEqual(first.build_id, again.build_id)
write(self.site, "theme.yaml", dump_yaml(document("dark")))
workspace = (self.site / "theme.yaml").read_bytes()
second = build_site(self.site, self.out, now=NOW)
self.assertNotEqual(first.build_id, second.build_id)
rollback(self.out, first.build_id)
self.assertEqual((self.site / "theme.yaml").read_bytes(), workspace)
self.assertEqual((self.out / "current/manifest.json").read_bytes(), original_bytes)
def test_render_resource_change_changes_id_with_same_source(self):
first = build_site(self.site, self.out, now=NOW)
reg = load_site(self.site)
reg.fragments["hero"].style += "\n.f-hero { padding-top: 5rem; }"
with patch("site_engine.build.pipeline.load_site", return_value=reg):
second = build_site(self.site, self.out, now=NOW)
self.assertEqual(first.source_hash, second.source_hash)
self.assertNotEqual(first.build_id, second.build_id)
self.assertTrue(first.output_dir.exists())
def test_existing_release_is_never_overwritten_on_collision(self):
first = build_site(self.site, self.out, now=NOW)
(first.output_dir / "index.html").write_text("Historical content")
with self.assertRaises(EngineError) as caught:
build_site(self.site, self.out, now=NOW)
self.assertIn("E_RELEASE_COLLISION", caught.exception.report.codes())
self.assertEqual((first.output_dir / "index.html").read_text(), "Historical content")
self.assertFalse(list(self.out.glob(".staging*")))