#!/usr/bin/env python3
"""Validate a dashboard blueprint JSON file and render a self-contained HTML wireframe."""
from __future__ import annotations
import argparse
import html
import json
import re
import sys
from pathlib import Path
from typing import Any
TOP_KEYS = {"title", "subtitle", "width", "height", "columns", "theme", "zones", "filters", "notes"}
ZONE_KEYS = {"id", "title", "kind", "x", "y", "w", "h", "details"}
THEME_KEYS = {"primary", "background", "surface", "text"}
DEFAULT_THEME = {"primary": "#2563EB", "background": "#F8FAFC", "surface": "#FFFFFF", "text": "#172033"}
HEX = re.compile(r"^#[0-9A-Fa-f]{6}$")
class SpecError(ValueError):
"""Raised when the wireframe contract is violated."""
def text_value(value: Any, label: str, maximum: int = 200) -> str:
if not isinstance(value, str) or not value.strip():
raise SpecError(f"{label} must be a non-empty string")
value = value.strip()
if len(value) > maximum:
raise SpecError(f"{label} exceeds {maximum} characters")
return value
def int_value(value: Any, label: str, minimum: int, maximum: int) -> int:
if isinstance(value, bool) or not isinstance(value, int) or not minimum <= value <= maximum:
raise SpecError(f"{label} must be an integer from {minimum} to {maximum}")
return value
def string_list(value: Any, label: str, maximum_items: int = 12) -> list[str]:
if not isinstance(value, list) or len(value) > maximum_items:
raise SpecError(f"{label} must be an array of at most {maximum_items} strings")
return [text_value(item, f"{label}[{index}]") for index, item in enumerate(value)]
def validate(payload: Any) -> dict[str, Any]:
if not isinstance(payload, dict):
raise SpecError("input must be a JSON object")
missing = {"title", "width", "height", "columns", "zones"} - set(payload)
extra = set(payload) - TOP_KEYS
if missing:
raise SpecError(f"missing top-level keys: {sorted(missing)}")
if extra:
raise SpecError(f"unknown top-level keys: {sorted(extra)}")
width = int_value(payload["width"], "width", 320, 3840)
height = int_value(payload["height"], "height", 320, 2160)
columns = int_value(payload["columns"], "columns", 1, 24)
zones_raw = payload["zones"]
if not isinstance(zones_raw, list) or not zones_raw or len(zones_raw) > 30:
raise SpecError("zones must be an array containing 1 to 30 objects")
zones, ids, cells = [], set(), set()
for index, zone in enumerate(zones_raw):
if not isinstance(zone, dict):
raise SpecError(f"zones[{index}] must be an object")
missing_zone = {"id", "title", "kind", "x", "y", "w", "h"} - set(zone)
extra_zone = set(zone) - ZONE_KEYS
if missing_zone:
raise SpecError(f"zones[{index}] missing keys: {sorted(missing_zone)}")
if extra_zone:
raise SpecError(f"zones[{index}] has unknown keys: {sorted(extra_zone)}")
zone_id = text_value(zone["id"], f"zones[{index}].id", 64)
if zone_id in ids:
raise SpecError(f"duplicate zone id: {zone_id}")
ids.add(zone_id)
x = int_value(zone["x"], f"zones[{index}].x", 1, columns)
y = int_value(zone["y"], f"zones[{index}].y", 1, 50)
w = int_value(zone["w"], f"zones[{index}].w", 1, columns)
h = int_value(zone["h"], f"zones[{index}].h", 1, 50)
if x + w - 1 > columns:
raise SpecError(f"zones[{index}] exceeds the {columns}-column grid")
occupied = {(column, row) for column in range(x, x + w) for row in range(y, y + h)}
if cells & occupied:
raise SpecError(f"zones[{index}] overlaps another zone")
cells |= occupied
zones.append({
"id": zone_id,
"title": text_value(zone["title"], f"zones[{index}].title"),
"kind": text_value(zone["kind"], f"zones[{index}].kind", 40),
"x": x, "y": y, "w": w, "h": h,
"details": string_list(zone.get("details", []), f"zones[{index}].details", 8),
})
theme_raw = payload.get("theme", {})
if not isinstance(theme_raw, dict) or set(theme_raw) - THEME_KEYS:
raise SpecError(f"theme supports only: {sorted(THEME_KEYS)}")
theme = {**DEFAULT_THEME, **theme_raw}
for key, value in theme.items():
if not isinstance(value, str) or not HEX.fullmatch(value):
raise SpecError(f"theme.{key} must be a six-digit hex color")
subtitle = payload.get("subtitle", "")
if subtitle:
subtitle = text_value(subtitle, "subtitle")
return {
"title": text_value(payload["title"], "title"),
"subtitle": subtitle,
"width": width,
"height": height,
"columns": columns,
"theme": theme,
"zones": zones,
"filters": string_list(payload.get("filters", []), "filters"),
"notes": string_list(payload.get("notes", []), "notes"),
}
def render(spec: dict[str, Any]) -> str:
esc = html.escape
theme = spec["theme"]
zone_html = []
for zone in spec["zones"]:
details = "".join(f"
{esc(item)}
" for item in zone["details"])
zone_html.append(
f''
f'
{esc(zone["kind"])}
{esc(zone["title"])}
{details}
'
)
filters = "".join(f"{esc(item)}" for item in spec["filters"])
notes = "".join(f"
{esc(item)}
" for item in spec["notes"])
subtitle = f'
{esc(spec["subtitle"])}
' if spec["subtitle"] else ""
return f"""
{esc(spec['title'])} — wireframe
{esc(spec['title'])}
{subtitle}
{''.join(zone_html)}
"""
def main() -> int:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("input", type=Path, help="wireframe JSON specification")
parser.add_argument("output", type=Path, help="HTML output path")
parser.add_argument("--force", action="store_true", help="replace an existing output file")
args = parser.parse_args()
try:
with args.input.open(encoding="utf-8") as handle:
spec = validate(json.load(handle))
if not args.output.parent.is_dir():
raise SpecError(f"output directory does not exist: {args.output.parent}")
if args.input.resolve() == args.output.resolve():
raise SpecError("input and output paths must differ")
if args.output.exists() and not args.force:
raise SpecError("output already exists; use --force only after confirming replacement")
args.output.write_text(render(spec), encoding="utf-8")
except (OSError, json.JSONDecodeError, SpecError) as exc:
print(f"error: {exc}", file=sys.stderr)
return 2
print(args.output.resolve())
return 0
if __name__ == "__main__":
raise SystemExit(main())