pydzn 0.1.3__py3-none-any.whl → 0.1.4__py3-none-any.whl

pydzn/components/sidebar/component.py

@@ -1,15 +1,70 @@
 from pydzn.base_component import BaseComponent
+from pydzn.variants import VariantSupport
 
 
-class Sidebar(BaseComponent):
+class Sidebar(VariantSupport, BaseComponent):
     """
-    Minimal sidebar container.
-    Spans parent height; default subtle panel bg.
-    The layout decides which side shows the divider.
+    Sidebar container with pluggable variants.
+    NOTE: No side-specific borders/shadows here — the layout decides the divider/shadow.
     """
 
-    def __init__(self, *, children: str | None = None, tag: str = "div", dzn: str | None = None, **attrs):
-        super().__init__(children=children or "", tag=tag, dzn=dzn, **attrs)
+    # Visual “shells” (theme-aware names play nice if your theme defines bg-elevated/bg-surface/etc.)
+    VARIANTS = {
+        # transparent shells
+        "bare":            "bg-[transparent] shadow-none border-0",
+        "ghost":           "bg-[transparent] shadow-none",
+
+        # neutral panels
+        "panel":           "bg-elevated shadow-none",
+        "panel-soft":      "bg-[rgba(15,23,42,.03)] shadow-none",
+        "panel-elevated":  "bg-elevated shadow-sm",
+        "panel-elevated-lg":"bg-elevated shadow-md",
+        "muted":           "bg-surface shadow-none",
+
+        # fun
+        "glass":           "bg-[rgba(255,255,255,.6)] shadow-sm",
+    }
+
+    # Inner padding “sizes”
+    SIZES = {
+        "xs": "p-2",
+        "sm": "p-3",
+        "md": "p-4",
+        "lg": "p-6",
+    }
+
+    # Tones optional (left empty since variants already choose a look)
+    TONES = {}
+
+    # Project-wide defaults (overridable via VariantSupport.set_default_choices)
+    DEFAULTS = {
+        "variant": "panel",
+        "size": "md",
+        "tone": "",
+    }
+
+    def __init__(
+        self,
+        *,
+        children: str | None = None,
+        tag: str = "aside",
+        variant: str | None = None,
+        size: str | None = None,
+        tone: str | None = None,
+        dzn: str | None = None,    # extra raw utilities merged last
+        **attrs,
+    ):
+        # allow stray attrs["dzn"]
+        extra_dzn = dzn or attrs.pop("dzn", None)
+
+        effective_dzn = self._resolve_variant_dzn(
+            variant=variant,
+            size=size,
+            tone=tone,
+            extra_dzn=extra_dzn,
+        )
+
+        super().__init__(children=children or "", tag=tag, dzn=effective_dzn, **attrs)
 
     def context(self) -> dict:
         return {}

pydzn/dzn.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 import re
 from typing import Iterable
 
+
 # --- tokens (extend as needed) ---
 TOKENS = {
     "space": {
@@ -74,6 +75,10 @@ def emit_base(name: str) -> str | None:
         case "justify-center":  return rule(name, "justify-content:center")
         case "text-center":     return rule(name, "text-align:center")
 
+        case "self-center": return rule(name, "align-self:center")
+        case "self-start":  return rule(name, "align-self:flex-start")
+        case "self-end":    return rule(name, "align-self:flex-end")
+
         # border (longhand for predictable overrides)
         case "border":
             return rule(name,
@@ -132,6 +137,40 @@ def emit_base(name: str) -> str | None:
 
         case "aspect-square": return rule(name, "aspect-ratio:1/1")
 
+        # auto margins (centering helpers)
+        case "mx-auto": return rule(name, "margin-left:auto;margin-right:auto")
+        case "ml-auto": return rule(name, "margin-left:auto")
+        case "mr-auto": return rule(name, "margin-right:auto")
+        case "ms-auto": return rule(name, "margin-inline-start:auto")   # logical
+        case "me-auto": return rule(name, "margin-inline-end:auto")     # logical
+
+        # positioning
+        case "sticky":      return rule(name, "position:sticky")
+        case "top-0":       return rule(name, "top:0")
+
+        # overflow helpers
+        case "overflow-hidden":   return rule(name, "overflow:hidden")
+        case "overflow-auto":     return rule(name, "overflow:auto")
+        case "overflow-y-auto":   return rule(name, "overflow-y:auto")
+        case "overflow-x-hidden": return rule(name, "overflow-x:hidden")
+        case "overflow-y-hidden": return rule(name, "overflow-y:hidden")
+
+        # overscroll-behavior
+        case "overscroll-auto":    return rule(name, "overscroll-behavior:auto")
+        case "overscroll-contain": return rule(name, "overscroll-behavior:contain")
+        case "overscroll-none":    return rule(name, "overscroll-behavior:none")
+
+        # optional: keep layout from shifting when scrollbar appears
+        case "scrollbar-stable":   return rule(name, "scrollbar-gutter:stable")
+
+        # text decoration (links etc.)
+        case "no-underline":    return rule(name, "text-decoration:none")
+        case "underline":       return rule(name, "text-decoration:underline")
+        case "line-through":    return rule(name, "text-decoration:line-through")
+        case "decoration-solid":  return rule(name, "text-decoration-style:solid")
+        case "decoration-dashed": return rule(name, "text-decoration-style:dashed")
+        case "decoration-dotted": return rule(name, "text-decoration-style:dotted")
+
     return None
 
 def emit_scale(name: str) -> str | None:
@@ -199,6 +238,36 @@ def emit_scale(name: str) -> str | None:
         prop = {"tl":"top-left","tr":"top-right","br":"bottom-right","bl":"bottom-left"}[corner]
         return rule(name, f"border-{prop}-radius:{val}")
 
+    # --- margin scale ---
+    if m := re.fullmatch(r"m-(\d+)", name):
+        if (val := TOKENS["space"].get(m.group(1))) is not None:
+            return rule(name, f"margin:{val}")
+    if m := re.fullmatch(r"mx-(\d+)", name):
+        if (val := TOKENS["space"].get(m.group(1))) is not None:
+            return rule(name, f"margin-left:{val};margin-right:{val}")
+    if m := re.fullmatch(r"my-(\d+)", name):
+        if (val := TOKENS["space"].get(m.group(1))) is not None:
+            return rule(name, f"margin-top:{val};margin-bottom:{val}")
+    if m := re.fullmatch(r"mt-(\d+)", name):
+        if (val := TOKENS["space"].get(m.group(1))) is not None:
+            return rule(name, f"margin-top:{val}")
+    if m := re.fullmatch(r"mr-(\d+)", name):
+        if (val := TOKENS["space"].get(m.group(1))) is not None:
+            return rule(name, f"margin-right:{val}")
+    if m := re.fullmatch(r"mb-(\d+)", name):
+        if (val := TOKENS["space"].get(m.group(1))) is not None:
+            return rule(name, f"margin-bottom:{val}")
+    if m := re.fullmatch(r"ml-(\d+)", name):
+        if (val := TOKENS["space"].get(m.group(1))) is not None:
+            return rule(name, f"margin-left:{val}")
+    # logical (RTL-aware)
+    if m := re.fullmatch(r"ms-(\d+)", name):
+        if (val := TOKENS["space"].get(m.group(1))) is not None:
+            return rule(name, f"margin-inline-start:{val}")
+    if m := re.fullmatch(r"me-(\d+)", name):
+        if (val := TOKENS["space"].get(m.group(1))) is not None:
+            return rule(name, f"margin-inline-end:{val}")
+
     return None
 
 def emit_arbitrary(name: str) -> str | None:
@@ -252,6 +321,33 @@ def emit_arbitrary(name: str) -> str | None:
         v = m.group(1).replace("_", " ")
         return rule(css_escape_class(name), f"grid-template-rows:{v}")
 
+    # z-index arbitrary
+    if m := re.fullmatch(r"z-\[(.+?)\]", name):
+        return rule(esel, f"z-index:{m.group(1)}")
+
+    if m := re.fullmatch(r"top-\[(.+?)\]", name):
+        return rule(esel, f"top:{m.group(1)}")
+
+    # margin arbitrary (supports logical too)
+    if m := re.fullmatch(r"m-\[(.+?)\]", name):
+        return rule(esel, f"margin:{m.group(1)}")
+    if m := re.fullmatch(r"mx-\[(.+?)\]", name):
+        v = m.group(1); return rule(esel, f"margin-left:{v};margin-right:{v}")
+    if m := re.fullmatch(r"my-\[(.+?)\]", name):
+        v = m.group(1); return rule(esel, f"margin-top:{v};margin-bottom:{v}")
+    if m := re.fullmatch(r"mt-\[(.+?)\]", name):
+        return rule(esel, f"margin-top:{m.group(1)}")
+    if m := re.fullmatch(r"mr-\[(.+?)\]", name):
+        return rule(esel, f"margin-right:{m.group(1)}")
+    if m := re.fullmatch(r"mb-\[(.+?)\]", name):
+        return rule(esel, f"margin-bottom:{m.group(1)}")
+    if m := re.fullmatch(r"ml-\[(.+?)\]", name):
+        return rule(esel, f"margin-left:{m.group(1)}")
+    if m := re.fullmatch(r"ms-\[(.+?)\]", name):
+        return rule(esel, f"margin-inline-start:{m.group(1)}")
+    if m := re.fullmatch(r"me-\[(.+?)\]", name):
+        return rule(esel, f"margin-inline-end:{m.group(1)}")
+
     return None
 
 # --- variants ---

pydzn/grid_builder.py

@@ -28,7 +28,7 @@ class _Region:
     name: str
     col_name: str
     row_name: Optional[str]           # if None, will resolve to first row
-    col_span: int = 1
+    col_span: Union[int, str] = 1     # NEW: allow "all" -> 1 / -1
     row_span: Optional[int] = 1       # if None => span all rows
     dzn: str = ""
 
@@ -38,7 +38,11 @@ class _Region:
     _row_span_resolved: int = 1
 
     def placement_style(self) -> str:
-        gc = f"{self._col_index} / span {self.col_span}"
+        # If col_span is "all", always span first-to-last column; ignore col_name
+        if isinstance(self.col_span, str) and self.col_span.lower() == "all":
+            gc = "1 / -1"
+        else:
+            gc = f"{self._col_index} / span {self.col_span}"
         gr = f"{self._row_index} / span {self._row_span_resolved}"
         return f"grid-column:{gc};grid-row:{gr};"
 
@@ -72,7 +76,10 @@ class GridLayoutBuilder:
         self._named_rows: List[Tuple[str, str]] = [("content", "1fr")]
         self._regions: List[_Region] = []
         self._outer_dzn: str = ""          # keep empty by default (no forced classes)
-        self._height_css: str = "100vh"    # default grid height
+        self._height_css: str = "100vh"    # default grid height value
+        # NEW: which CSS property to use for height control ("min-height" | "height" | "both")
+        self._height_property: str = "min-height"
+        self._height_apply_to: str = "container"  # 'outer' | 'container' | 'both'
 
     # ---------------- tracks (named & ordered) ----------------
     def columns(self, **spec: CSSVal) -> "GridLayoutBuilder":
@@ -103,8 +110,19 @@ class GridLayoutBuilder:
         self._named_rows.append((name, _css_px(height)))
         return self
 
-    def fill_height(self, css_value: str = "100vh") -> "GridLayoutBuilder":
+    def fill_height(self, css_value: str = "100vh", *, property: str = "min-height", apply_to: str = "container"):
+        """
+        Control vertical sizing.
+          - property: "min-height" | "height" | "both"
+          - apply_to: "container" (inner grid), "outer" (outer wrapper), or "both"
+        """
+        if property not in ("min-height", "height", "both"):
+            raise ValueError("fill_height(property=...) must be 'min-height', 'height', or 'both'")
+        if apply_to not in ("container", "outer", "both"):
+            raise ValueError("fill_height(apply_to=...) must be 'container', 'outer', or 'both'")
         self._height_css = css_value
+        self._height_property = property
+        self._height_apply_to = apply_to
         return self
 
     # ---------------- convenience shapes ----------------
@@ -127,15 +145,19 @@ class GridLayoutBuilder:
         *,
         col: str,
         row: Optional[str],
-        col_span: int = 1,
-        row_span: Optional[int] = 1,  # None = span all rows
+        col_span: Union[int, str] = 1,   # NEW: accept "all"
+        row_span: Optional[int] = 1,     # None = span all rows
         dzn: str = "",
     ) -> "GridLayoutBuilder":
         """
         Add a region by track names. Example:
           .region("sidebar", col="sidebar", row=None, row_span=None)  # full height
-          .region("hero",    col="main", row="hero")
-          .region("content", col="main", row="content")
+          .region("hero",    col="main",    row="hero")
+          .region("content", col="main",    row="content")
+
+        Special:
+          - col_span="all" → emits grid-column: 1 / -1 (spans every defined column).
+            In this mode, the provided `col` is ignored.
         """
         self._regions.append(
             _Region(
@@ -166,9 +188,11 @@ class GridLayoutBuilder:
         resolved: Dict[str, _Region] = {}
         order: List[str] = []
         for r in self._regions:
-            if r.col_name not in col_index:
-                raise ValueError(f"Unknown column '{r.col_name}' for region '{r.name}'")
-            r._col_index = col_index[r.col_name]
+            # Only compute a column index if we are NOT spanning all columns
+            if not (isinstance(r.col_span, str) and r.col_span.lower() == "all"):
+                if r.col_name not in col_index:
+                    raise ValueError(f"Unknown column '{r.col_name}' for region '{r.name}'")
+                r._col_index = col_index[r.col_name]
 
             if r.row_name is None:
                 r._row_index = 1
@@ -183,6 +207,8 @@ class GridLayoutBuilder:
             order.append(r.name)
 
         height_css = self._height_css
+        height_prop = self._height_property
+        height_apply_to = self._height_apply_to
 
         class _Layout:
             __slots__ = ("_grid_cols", "_grid_rows", "_regions", "_order",
@@ -211,13 +237,33 @@ class GridLayoutBuilder:
             def render(self, **slots: str) -> str:
                 # outer wrapper (no template)
                 outer_attr = f' class="{html.escape(self._outer_dzn)}"' if self._outer_dzn else ""
-                # ensure grid without relying on dzn
-                grid_style = f"display:grid;min-height:{html.escape(height_css)};"
                 grid_class = f"{self._grid_cols} {self._grid_rows}".strip()
 
+                # Build styles conditionally based on fill_height settings
+                outer_style_parts: List[str] = []
+                # FIX: add semicolon after display:grid;
+                grid_style_parts:  List[str] = ["display:grid;"]
+
+                def _apply_height(parts: List[str]):
+                    if height_prop == "both":
+                        parts.append(f"height:{html.escape(height_css)};")
+                        parts.append(f"min-height:{html.escape(height_css)};")
+                    elif height_prop == "height":
+                        parts.append(f"height:{html.escape(height_css)};")
+                    else:
+                        parts.append(f"min-height:{html.escape(height_css)};")
+
+                if height_apply_to in ("outer", "both"):
+                    _apply_height(outer_style_parts)
+                if height_apply_to in ("container", "both"):
+                    _apply_height(grid_style_parts)
+
+                outer_style_attr = f' style="{"".join(outer_style_parts)}"' if outer_style_parts else ""
+                grid_style_attr  = f' style="{"".join(grid_style_parts)}"'
+
                 out: List[str] = []
-                out.append(f"<div{outer_attr}>")
-                out.append(f'  <div class="{html.escape(grid_class)}" style="{grid_style}">')
+                out.append(f"<div{outer_attr}{outer_style_attr}>")
+                out.append(f'  <div class="{html.escape(grid_class)}"{grid_style_attr}>')
 
                 for name in self._order:
                     R = self._regions[name]
@@ -226,16 +272,29 @@ class GridLayoutBuilder:
                     region_cls_attr = f' class="{html.escape(region_cls)}"' if region_cls else ""
                     region_style_attr = f' style="{html.escape(R.placement_style())}"'
 
+                    # add debug outline; make wrapper a positioning context only if it's static
                     if self._debug:
-                        dbg = "outline:1px dashed rgba(220,38,38,.55);outline-offset:-1px;"
+                        dbg_outline = "outline:1px dashed rgba(220,38,38,.55);outline-offset:-1px;"
+
+                        # figure out if region already positions itself via classes
+                        # (so we DON'T override fixed/absolute/sticky/relative with inline styles)
+                        has_pos = False
+                        if region_cls:
+                            pos_tokens = {"fixed", "absolute", "relative", "sticky"}
+                            has_pos = any(tok in region_cls.split() for tok in pos_tokens)
+
+                        dbg = dbg_outline + ("" if has_pos else "position:relative;")
                         region_style_attr = region_style_attr[:-1] + dbg + '"'  # append
 
                     out.append(f'    <div data-region="{html.escape(name)}"{region_cls_attr}{region_style_attr}>')
 
                     if self._debug:
                         out.append(
-                            '      <div style="font:11px/1.2 system-ui, -apple-system, Segoe UI, Roboto;'
-                            'color:rgba(220,38,38,.8);padding:2px 4px;display:inline-block;">'
+                            '      <div style="position:absolute;top:2px;left:2px;z-index:1;'
+                            'font:11px/1.2 system-ui, -apple-system, Segoe UI, Roboto;'
+                            'color:rgba(220,38,38,.8);padding:2px 4px;'
+                            'background:rgba(255,255,255,.6);border-radius:3px;'
+                            'pointer-events:none;">'
                             f'{html.escape(name)}</div>'
                         )
 

pydzn/responsive.py

@@ -0,0 +1,24 @@
+import uuid
+
+
+def responsive_pair(desktop_html: str, mobile_html: str, md_min_px: int = 768) -> str:
+    """Return both DOM trees with CSS that shows exactly one, scoped to a unique wrapper."""
+    uid = uuid.uuid4().hex[:8]
+    cls = f"resp-pair-{uid}"
+    css = f"""
+<style>
+.{cls} ._desktop {{ display: none; }}
+.{cls} ._mobile  {{ display: block; }}
+@media (min-width:{md_min_px}px) {{
+  .{cls} ._desktop {{ display: block; }}
+  .{cls} ._mobile  {{ display: none;  }}
+}}
+</style>
+"""
+    return (
+        css
+        + f'<div class="{cls}">'
+        + f'  <div class="_mobile">{mobile_html}</div>'
+        + f'  <div class="_desktop">{desktop_html}</div>'
+        + f'</div>'
+    )

pydzn/variants.py

@@ -0,0 +1,215 @@
+from __future__ import annotations
+from typing import ClassVar, Dict, Iterable, Mapping, Optional
+from pydzn.dzn import register_dzn_classes
+
+
+class VariantSupport:
+    """
+    Mixin for components that want tailwind-like 'variant/size/tone' presets
+    with pluggable, namespaced libraries.
+
+    Subclasses typically define:
+      VARIANTS: Mapping[str, str]
+      SIZES:    Mapping[str, str]
+      TONES:    Mapping[str, str]
+      DEFAULTS: Mapping[str, str]  # e.g. {"variant":"outline-primary", "size":"md", "tone":""}
+
+    Public API on each component class:
+      - attach_variant_library(namespace, variants=..., sizes=..., tones=..., override=False)
+      - set_default_choices(variant=..., size=..., tone=...)
+      - list_variants(namespaced=True) -> list[str]
+      - list_sizes(namespaced=True) -> list[str]
+      - list_tones(namespaced=True) -> list[str]
+      - available_options(namespaced=True) -> dict with "variants"/"sizes"/"tones"/"defaults"
+
+    Instance-side helper used by __init__ of the component:
+      - _resolve_variant_dzn(variant, size, tone, extra_dzn) -> str
+    """
+
+    # Per-subclass external libs: { "ns": {"variants":{...}, "sizes":{...}, "tones":{...}} }
+    _external_libs: ClassVar[Dict[str, Dict[str, Dict[str, str]]]]
+
+    def __init_subclass__(cls, **kwargs):
+        super().__init_subclass__(**kwargs)
+        # init per-class registry
+        if not hasattr(cls, "_external_libs"):
+            cls._external_libs = {}
+        # sane fallbacks so list_* never explode
+        for attr, default in (("VARIANTS", {}), ("SIZES", {}), ("TONES", {}), ("DEFAULTS", {})):
+            if not hasattr(cls, attr):
+                setattr(cls, attr, default)
+
+    # ---------- library plumbing ----------
+
+    @classmethod
+    def attach_variant_library(
+        cls,
+        namespace: str,
+        *,
+        variants: Optional[Mapping[str, str]] = None,
+        sizes: Optional[Mapping[str, str]] = None,
+        tones: Optional[Mapping[str, str]] = None,
+        override: bool = False,
+    ) -> None:
+        """
+        Attach or extend a namespaced library for this component class only.
+        Example:
+            Button.attach_variant_library(
+                "acme",
+                variants={"glass": "px-5 py-2 rounded-md bg-[rgba(...", ...},
+                sizes={"xl": "px-7 py-4"},
+                tones={"success": "bg-[..."}
+            )
+        """
+        ns = namespace.strip()
+        if not ns:
+            raise ValueError("attach_variant_library: namespace cannot be empty")
+
+        lib = cls._external_libs.get(ns, {"variants": {}, "sizes": {}, "tones": {}})
+        if override:
+            lib = {
+                "variants": dict(variants or {}),
+                "sizes": dict(sizes or {}),
+                "tones": dict(tones or {}),
+            }
+        else:
+            if variants:
+                lib["variants"].update(variants)
+            if sizes:
+                lib["sizes"].update(sizes)
+            if tones:
+                lib["tones"].update(tones)
+
+        cls._external_libs[ns] = lib
+
+        # Register DZN so emitted CSS includes these utilities
+        all_classes: list[str] = []
+        for m in (variants or {}).values():
+            all_classes.append(m)
+        for m in (sizes or {}).values():
+            all_classes.append(m)
+        for m in (tones or {}).values():
+            all_classes.append(m)
+        if all_classes:
+            register_dzn_classes(" ".join(all_classes))
+
+    @classmethod
+    def set_default_choices(
+        cls,
+        *,
+        variant: Optional[str] = None,
+        size: Optional[str] = None,
+        tone: Optional[str] = None,
+    ) -> None:
+        d = dict(getattr(cls, "DEFAULTS", {}))
+        if variant is not None:
+            d["variant"] = variant
+        if size is not None:
+            d["size"] = size
+        if tone is not None:
+            d["tone"] = tone
+        cls.DEFAULTS = d
+
+    # ---------- listing helpers (what you asked for) ----------
+
+    @classmethod
+    def list_variants(cls, *, namespaced: bool = True) -> list[str]:
+        """
+        Return all available variant keys.
+        If namespaced=True, external libs appear as 'ns:key'.
+        """
+        keys: list[str] = list(getattr(cls, "VARIANTS", {}).keys())
+        if namespaced:
+            for ns, lib in cls._external_libs.items():
+                keys.extend([f"{ns}:{k}" for k in lib.get("variants", {}).keys()])
+        else:
+            # note: non-namespaced duplicates could collide; this is just the names
+            for lib in cls._external_libs.values():
+                keys.extend(lib.get("variants", {}).keys())
+        return sorted(keys)
+
+    @classmethod
+    def list_sizes(cls, *, namespaced: bool = True) -> list[str]:
+        keys: list[str] = list(getattr(cls, "SIZES", {}).keys())
+        if namespaced:
+            for ns, lib in cls._external_libs.items():
+                keys.extend([f"{ns}:{k}" for k in lib.get("sizes", {}).keys()])
+        else:
+            for lib in cls._external_libs.values():
+                keys.extend(lib.get("sizes", {}).keys())
+        return sorted(set(keys))
+
+    @classmethod
+    def list_tones(cls, *, namespaced: bool = True) -> list[str]:
+        keys: list[str] = list(getattr(cls, "TONES", {}).keys())
+        if namespaced:
+            for ns, lib in cls._external_libs.items():
+                keys.extend([f"{ns}:{k}" for k in lib.get("tones", {}).keys()])
+        else:
+            for lib in cls._external_libs.values():
+                keys.extend(lib.get("tones", {}).keys())
+        return sorted(set(keys))
+
+    @classmethod
+    def available_options(cls, *, namespaced: bool = True) -> dict:
+        """
+        Structured view for UIs: { variants: [...], sizes: [...], tones: [...], defaults: {...} }
+        """
+        return {
+            "variants": cls.list_variants(namespaced=namespaced),
+            "sizes": cls.list_sizes(namespaced=namespaced),
+            "tones": cls.list_tones(namespaced=namespaced),
+            "defaults": dict(getattr(cls, "DEFAULTS", {})),
+        }
+
+    # ---------- resolution used by your component __init__ ----------
+
+    @classmethod
+    def _lookup_variant_piece(cls, kind: str, key: Optional[str]) -> str:
+        """
+        kind = 'variants' | 'sizes' | 'tones'
+        key may be namespaced 'ns:name'. Returns DZN string or ''.
+        """
+        if not key:
+            return ""
+
+        # external: ns:key
+        if ":" in key:
+            ns, name = key.split(":", 1)
+            lib = cls._external_libs.get(ns, {})
+            return lib.get(kind, {}).get(name, "")
+
+        # built-in
+        table = getattr(cls, kind.upper(), {})
+        return table.get(key, "")
+
+    def _resolve_variant_dzn(
+        self,
+        *,
+        variant: Optional[str],
+        size: Optional[str],
+        tone: Optional[str],
+        extra_dzn: Optional[str] = None,
+    ) -> str:
+        cls = self.__class__
+        defaults = getattr(cls, "DEFAULTS", {})
+
+        v_key = variant if variant is not None else defaults.get("variant", "")
+        s_key = size    if size    is not None else defaults.get("size", "")
+        t_key = tone    if tone    is not None else defaults.get("tone", "")
+
+        parts: list[str] = []
+        v = cls._lookup_variant_piece("variants", v_key)
+        if v: parts.append(v)
+        s = cls._lookup_variant_piece("sizes", s_key)
+        if s: parts.append(s)
+        t = cls._lookup_variant_piece("tones", t_key)
+        if t: parts.append(t)
+        if extra_dzn:
+            parts.append(extra_dzn)
+        resolved = " ".join(p for p in parts if p).strip()
+
+        # register resolved classes once more (cheap) so /_dzn.css emits them
+        if resolved:
+            register_dzn_classes(resolved)
+        return resolved