Skip to content

Constraint Expressions (DSL Reference)

expr("...") is Rezi’s constraint expression escape hatch. It’s used for derived layout relationships (parent/viewport/sibling/intrinsic).

Prefer the helper layer for common patterns: - docs/reference/constraints-api.md - docs/guide/constraints.md

Where expressions are allowed

Constraint expressions are accepted on supported layout props such as:

  • width, height
  • minWidth, minHeight, maxWidth, maxHeight
  • flexBasis
  • display (layout-driven visibility)

Notably, grid.columns is not expression-enabled in the alpha contract:

ui.grid({ columns: 3 }, children)              // ok
ui.grid({ columns: "14 auto 1fr" }, children) // ok
ui.grid({ columns: expr("...") }, children)   // invalid in alpha

References

Inside expr("..."), these references are supported:

  • parent.w, parent.h — parent content size
  • viewport.w, viewport.h — terminal viewport size
  • intrinsic.w, intrinsic.h — widget’s measured natural size (when available)
  • #id.w, #id.h, #id.min_w, #id.min_h — sibling widget metrics

Notes: - Direct #id.* references require a unique target id in scope. - Shared ids are allowed (for non-interactive nodes) but must be used with sibling aggregation functions (max_sibling, sum_sibling) to avoid ambiguity. - max_sibling / sum_sibling only aggregate matching ids that share the same parent as the consuming widget.

Operators and syntax

Supported operators:

  • Arithmetic: +, -, *, /
  • Comparisons: >, >=, <, <=, ==, !=
  • Ternary: cond ? then : else
  • Grouping: ( ... )

There is no && / || operator. Combine conditions using if(...) or ternary.

Comparison operators evaluate to numeric truthiness: - true → 1 - false → 0

Division by zero evaluates deterministically as 0.

Function allowlist

Supported functions:

  • clamp(min, value, max)
  • min(a, b)
  • max(a, b)
  • floor(x)
  • ceil(x)
  • round(x)
  • abs(x)
  • if(cond, then, else) (cond > 0 is truthy)
  • max_sibling(#id.<metric>)
  • sum_sibling(#id.<metric>)
  • steps(value, t1: r1, t2: r2, ...)

Unknown function names are deterministic errors (ZRUI_INVALID_CONSTRAINT).

Examples

expr("parent.w * 0.5")
expr("clamp(20, viewport.w * 0.25, 50)")
expr("viewport.w >= 110 ? 1 : 0")
expr("if(viewport.w >= 120, 60, 100)")
expr("max(0, parent.w - #sidebar.w - #rail.w - 1)")
expr("max_sibling(#kv-key.min_w)")
expr("steps(viewport.w, 80: 10, 120: 20, 160: 30)")

steps(...) is a compact breakpoint helper: - returns the first matching value where input < threshold - uses the final provided value as the fallback when input exceeds all thresholds

Diagnostics

Parse-time (expr(...))

Invalid DSL syntax throws ConstraintSyntaxError and includes source + position.

Frame-time

Constraint and layout integration failures surface deterministically:

  • ZRUI_INVALID_CONSTRAINT — unknown function, unknown/ambiguous ref, invalid graph usage
  • ZRUI_CIRCULAR_CONSTRAINT — a dependency cycle was detected
  • ZRUI_INVALID_PROPS — constraint usage violates widget/layout contracts (for example % size strings, responsive-map size constraints, or grid.columns: expr(...))

See docs/guide/debugging-constraints.md for a diagnosis flow.