feat(ast): add ExprValue<T> struct for universal property type support

feat: introduce ExprValue<T> universal property type and TemplatePipeline

Centralize template expression resolution from 3 duplicated backend
preprocessors into a single Core pipeline. All element properties now
use ExprValue<T> which can hold either a typed literal or a raw
expression string, enabling expression support for non-string types
(int, float, bool, enum) that were previously silently lost.

Key changes:
- Add ExprValue<T> readonly struct with Resolve/Materialize pipeline
- Add TemplatePipeline orchestrating Expand -> Resolve -> Materialize
- Migrate all properties across 9 element types to ExprValue<T>
- Wire TemplatePipeline into Skia, ImageSharp, and SVG backends
- Strip backend preprocessors to font-only (delete SVG preprocessor)
- Add 38 new tests for ExprValue and TemplatePipeline

82 files changed, 5095 tests passing.

test: add ExprValue integration tests and expression-aware YAML parsing

Add YamlPropertyHelpers with expression detection for typed properties
(float, int, bool, enum) — preserves {{expressions}} instead of losing
them via TryParse. Update ElementParsers to use new helpers.
Add 19 integration tests covering expression support across all types.

docs: update wiki for ExprValue expression support in typed properties

Update Template-Expressions: add "Expressions in Typed Properties" section,
update processing order from 5 to 6 steps (Parse → Expand → Resolve →
Materialize → Layout → Render). Update Element-Reference with expression
support note on Common Properties section.

Author: RoboNET

docs/wiki/Element-Reference.md

@@ -14,6 +14,8 @@ For rendering options (antialiasing, format settings), see [[Render-Options]].
 
 All 10 element types (`flex`, `text`, `image`, `svg`, `qr`, `barcode`, `separator`, `table`, `each`, `if`) inherit these properties from the base `TemplateElement` class. You can use any of them on any element.
 
+> **Expression support:** All properties on all element types accept `{{expressions}}`. This includes typed properties like `opacity` (float), `grow`/`shrink` (float), `order` (int), `wrap` (bool on text, FlexWrap on flex), and enum properties like `display`, `position`, `align`. See [[Template-Expressions]] for details.
+
 ### Size Properties
 
 Control the explicit dimensions and constraints of an element. All size properties accept values in `px`, `%`, `em`, or `auto`. Plain numbers without a suffix are treated as pixels.

docs/wiki/Template-Expressions.md

@@ -1,9 +1,10 @@
 # Template Expressions
 
-FlexRender provides a template engine with variable substitution, loops, and conditionals. Expressions are processed in two layers:
+FlexRender provides a template engine with variable substitution, loops, and conditionals. Expressions are processed in three phases:
 
 1. **AST-level** (`TemplateExpander`) -- expands `type: each` and `type: if` elements into concrete elements based on data. This enables template caching.
-2. **Inline** (`TemplateProcessor`) -- resolves `{{variable}}` expressions in element property values after expansion.
+2. **Inline** (`TemplatePipeline`) -- resolves `{{variable}}` expressions in all element property values after expansion.
+3. **Materialization** -- resolved strings are parsed into their target types (float, int, bool, enum). This allows expressions to work in all property types, not just strings.
 
 ## Variable Substitution
 
@@ -27,7 +28,7 @@ Use `{{variable}}` syntax to insert data values into text and properties:
   content: "{{orders[0].items[2].name}}"
 ```
 
-Variables can be used in most string properties: `content`, `data`, `src`, `color`, and others.
+Variables can be used in **all** element properties -- including typed properties like numbers (`opacity`, `maxLines`, `size`), booleans (`wrap`, `showText`), and enums (`align`, `display`, `position`). When a typed property contains `{{`, the value is preserved as an expression during parsing, resolved at render time, and then parsed into the target type.
 
 ## Inline Expressions
 
@@ -762,17 +763,68 @@ The `condition` field supports inline expressions with filters. This enables cas
 
 ---
 
+## Expressions in Typed Properties
+
+All element properties accept `{{expressions}}`, including typed properties like floats, integers, booleans, and enums. This enables fully data-driven templates where any aspect of the layout can be controlled by data.
+
+```yaml
+# Expressions in numeric properties
+- type: text
+  content: "Dynamic opacity"
+  opacity: "{{theme.textOpacity}}"
+  maxLines: "{{layout.maxLines}}"
+
+# Expressions in boolean properties
+- type: barcode
+  data: "{{product.sku}}"
+  showText: "{{settings.showBarcodeText}}"
+
+# Expressions in enum properties
+- type: text
+  content: "Dynamic alignment"
+  align: "{{theme.alignment}}"
+
+# Expressions in size properties
+- type: qr
+  data: "{{payment.url}}"
+  size: "{{layout.qrSize}}"
+```
+
+How typed expressions work:
+
+1. When a typed property contains `{{`, the parser preserves the raw string as an `ExprValue<T>` expression instead of parsing it immediately
+2. After template expansion, the expression is resolved to a concrete string using the data context
+3. The resolved string is then parsed into the target type (e.g., `"0.5"` becomes `float 0.5`, `"true"` becomes `bool true`, `"center"` becomes `TextAlign.Center`)
+4. If parsing fails, the default value for that type is used (e.g., `1.0` for opacity, `null` for nullable properties)
+
+This works with all expression features -- arithmetic, filters, conditionals, and null coalescing:
+
+```yaml
+# Computed opacity with fallback
+- type: text
+  content: "Styled text"
+  opacity: "{{theme.opacity ?? 1}}"
+
+# Conditional boolean via expression
+- type: barcode
+  data: "{{sku}}"
+  showText: "{{#if printMode}}true{{else}}false{{/if}}"
+```
+
+---
+
 ## Processing Order
 
 Understanding the processing order helps with debugging:
 
-1. **Parse** -- YAML is parsed into an AST (Template with CanvasSettings + TemplateElement tree)
+1. **Parse** -- YAML is parsed into an AST. Typed properties containing `{{` are preserved as expressions
 2. **Expand** -- `type: each` and `type: if` elements are expanded based on data
-3. **Process** -- `{{variable}}` expressions are resolved in element properties
-4. **Layout** -- the flexbox engine computes positions and sizes
-5. **Render** -- elements are drawn to the output image
+3. **Resolve** -- `{{variable}}` expressions are resolved to concrete strings in all properties
+4. **Materialize** -- resolved strings are parsed into typed values (float, int, bool, enum)
+5. **Layout** -- the flexbox engine computes positions and sizes
+6. **Render** -- elements are drawn to the output image
 
-Template caching works because steps 1 (parse) and 2-5 (expand/process/layout/render) are separate. Parse once, then render many times with different data.
+Template caching works because step 1 (parse) is separate from steps 2-6 (expand/resolve/materialize/layout/render). Parse once, then process with different data for each render.
 
 ## See Also
 

examples/AstRenderExample/Program.cs

@@ -87,7 +87,7 @@
 Console.WriteLine("=============================");
 Console.WriteLine();
 Console.WriteLine("Building template from code (no YAML)...");
-Console.WriteLine($"  Canvas: {template.Canvas.Width}px wide, background {template.Canvas.Background}");
+Console.WriteLine($"  Canvas: {template.Canvas.Width}px wide, background {template.Canvas.Background.Value}");
 Console.WriteLine($"  Elements: {template.Elements.Count}");
 Console.WriteLine();
 

src/FlexRender.Barcode.ImageSharp.Render/Providers/BarcodeImageSharpProvider.cs

@@ -33,7 +33,7 @@ public Image<Rgba32> GenerateImage(BarcodeElement element, int width, int height
     {
         ArgumentNullException.ThrowIfNull(element);
 
-        if (string.IsNullOrEmpty(element.Data))
+        if (string.IsNullOrEmpty(element.Data.Value))
         {
             throw new ArgumentException("Barcode data cannot be empty.", nameof(element));
         }
@@ -43,26 +43,26 @@ public Image<Rgba32> GenerateImage(BarcodeElement element, int width, int height
             throw new ArgumentException("Barcode dimensions must be positive.");
         }
 
-        return element.Format switch
+        return element.Format.Value switch
         {
             BarcodeFormat.Code128 => GenerateCode128(element, width, height),
-            _ => throw new NotSupportedException($"Barcode format '{element.Format}' is not yet supported.")
+            _ => throw new NotSupportedException($"Barcode format '{element.Format.Value}' is not yet supported.")
         };
     }
 
     private static Image<Rgba32> GenerateCode128(BarcodeElement element, int targetWidth, int targetHeight)
     {
-        var pattern = Code128Encoding.BuildPattern(element.Data);
+        var pattern = Code128Encoding.BuildPattern(element.Data.Value);
 
         var totalUnits = pattern.Length;
         var barWidth = targetWidth / (float)totalUnits;
-        var barcodeHeight = element.ShowText
+        var barcodeHeight = element.ShowText.Value
             ? targetHeight - TextHeight - TextPadding
             : targetHeight;
 
-        var foreground = ParseColor(element.Foreground, Color.Black);
-        var background = element.Background is not null
-            ? ParseColor(element.Background, Color.Transparent)
+        var foreground = ParseColor(element.Foreground.Value, Color.Black);
+        var background = element.Background.Value is not null
+            ? ParseColor(element.Background.Value, Color.Transparent)
             : Color.Transparent;
 
         var image = new Image<Rgba32>(targetWidth, targetHeight);
@@ -80,7 +80,7 @@ private static Image<Rgba32> GenerateCode128(BarcodeElement element, int targetW
                 x += barWidth;
             }
 
-            if (element.ShowText)
+            if (element.ShowText.Value)
             {
                 var font = ResolveFont(TextHeight - 2);
                 var textY = barcodeHeight + TextPadding;
@@ -90,7 +90,7 @@ private static Image<Rgba32> GenerateCode128(BarcodeElement element, int targetW
                     HorizontalAlignment = HorizontalAlignment.Center,
                     VerticalAlignment = VerticalAlignment.Top
                 };
-                ctx.DrawText(options, element.Data, foreground);
+                ctx.DrawText(options, element.Data.Value, foreground);
             }
         });
 

src/FlexRender.Barcode.Skia.Render/Providers/BarcodeProvider.cs

@@ -64,24 +64,24 @@ public static SKBitmap Generate(BarcodeElement element, int? layoutWidth, int? l
     {
         ArgumentNullException.ThrowIfNull(element);
 
-        if (string.IsNullOrEmpty(element.Data))
+        if (string.IsNullOrEmpty(element.Data.Value))
         {
             throw new ArgumentException("Barcode data cannot be empty.", nameof(element));
         }
 
         // Priority order: layout dimensions > element dimensions > defaults (200x80)
-        var targetWidth = layoutWidth ?? element.BarcodeWidth ?? 200;
-        var targetHeight = layoutHeight ?? element.BarcodeHeight ?? 80;
+        var targetWidth = layoutWidth ?? element.BarcodeWidth.Value ?? 200;
+        var targetHeight = layoutHeight ?? element.BarcodeHeight.Value ?? 80;
 
         if (targetWidth <= 0 || targetHeight <= 0)
         {
             throw new ArgumentException("Barcode dimensions must be positive.", nameof(element));
         }
 
-        return element.Format switch
+        return element.Format.Value switch
         {
             BarcodeFormat.Code128 => GenerateCode128(element, targetWidth, targetHeight),
-            _ => throw new NotSupportedException($"Barcode format '{element.Format}' is not yet supported.")
+            _ => throw new NotSupportedException($"Barcode format '{element.Format.Value}' is not yet supported.")
         };
     }
 
@@ -107,21 +107,21 @@ private static SKBitmap GenerateBitmap(BarcodeElement element, int width, int he
     /// <returns>A bitmap containing the rendered Code 128 barcode.</returns>
     private static SKBitmap GenerateCode128(BarcodeElement element, int targetWidth, int targetHeight)
     {
-        var pattern = Code128Encoding.BuildPattern(element.Data);
+        var pattern = Code128Encoding.BuildPattern(element.Data.Value);
 
         // Calculate bar dimensions
         var totalUnits = pattern.Length;
         var barWidth = targetWidth / (float)totalUnits;
-        var barcodeHeight = element.ShowText
+        var barcodeHeight = element.ShowText.Value
             ? targetHeight - TextHeight - TextPadding
             : targetHeight;
 
         var bitmap = new SKBitmap(targetWidth, targetHeight);
         using var canvas = new SKCanvas(bitmap);
 
-        var foreground = ColorParser.Parse(element.Foreground);
-        var background = element.Background is not null
-            ? ColorParser.Parse(element.Background)
+        var foreground = ColorParser.Parse(element.Foreground.Value);
+        var background = element.Background.Value is not null
+            ? ColorParser.Parse(element.Background.Value)
             : SKColors.Transparent;
 
         // Fill background
@@ -146,7 +146,7 @@ private static SKBitmap GenerateCode128(BarcodeElement element, int targetWidth,
         }
 
         // Draw text if enabled
-        if (element.ShowText)
+        if (element.ShowText.Value)
         {
             using var typeface = SKTypeface.FromFamilyName("Arial", SKFontStyle.Normal) ?? SKTypeface.Default;
             using var textFont = new SKFont(typeface, TextHeight - 2)
@@ -160,7 +160,7 @@ private static SKBitmap GenerateCode128(BarcodeElement element, int targetWidth,
             };
 
             var textY = barcodeHeight + TextPadding + TextHeight - 2;
-            canvas.DrawText(element.Data, targetWidth / 2f, textY, SKTextAlign.Center, textFont, textPaint);
+            canvas.DrawText(element.Data.Value, targetWidth / 2f, textY, SKTextAlign.Center, textFont, textPaint);
         }
 
         return bitmap;

src/FlexRender.Barcode.Svg.Render/Providers/BarcodeSvgProvider.cs

@@ -36,27 +36,27 @@ public string GenerateSvgContent(BarcodeElement element, float width, float heig
     {
         ArgumentNullException.ThrowIfNull(element);
 
-        if (string.IsNullOrEmpty(element.Data))
+        if (string.IsNullOrEmpty(element.Data.Value))
         {
             throw new ArgumentException("Barcode data cannot be empty.", nameof(element));
         }
 
-        return element.Format switch
+        return element.Format.Value switch
         {
             BarcodeFormat.Code128 => GenerateCode128Svg(element, width, height),
-            _ => throw new NotSupportedException($"Barcode format '{element.Format}' is not yet supported.")
+            _ => throw new NotSupportedException($"Barcode format '{element.Format.Value}' is not yet supported.")
         };
     }
 
     private static string GenerateCode128Svg(BarcodeElement element, float width, float height)
     {
-        var pattern = Code128Encoding.BuildPattern(element.Data);
+        var pattern = Code128Encoding.BuildPattern(element.Data.Value);
 
         var totalUnits = pattern.Length;
         var barWidth = width / totalUnits;
 
-        var foreground = element.Foreground;
-        var background = element.Background;
+        var foreground = element.Foreground.Value;
+        var background = element.Background.Value;
 
         var sb = new StringBuilder(512);
         sb.Append("<g>");

src/FlexRender.Cli/Commands/DebugLayoutCommand.cs

@@ -197,7 +197,7 @@ private static string GetElementExtra(TemplateElement element)
         return element switch
         {
             FlexElement f => $" [{f.Direction.ToString().ToLowerInvariant()}]",
-            TextElement t => $" \"{Truncate(t.Content, 30)}\"",
+            TextElement t => $" \"{Truncate(t.Content.Value, 30)}\"",
             QrElement => " [qr]",
             BarcodeElement => " [barcode]",
             ImageElement => " [image]",

src/FlexRender.Cli/Commands/InfoCommand.cs

@@ -75,7 +75,7 @@ private static void PrintTemplateInfo(Template template, FileInfo templateFile)
         Console.WriteLine($"  Fixed dimension: {template.Canvas.Fixed}");
         Console.WriteLine($"  Width: {template.Canvas.Width}px");
         Console.WriteLine($"  Height: {template.Canvas.Height}px");
-        Console.WriteLine($"  Background: {template.Canvas.Background}");
+        Console.WriteLine($"  Background: {template.Canvas.Background.Value}");
         Console.WriteLine();
 
         Console.WriteLine("Elements:");
@@ -129,7 +129,7 @@ private static IEnumerable<string> ExtractVariables(Template template)
         {
             if (element is TextElement textElement)
             {
-                var matches = pattern.Matches(textElement.Content);
+                var matches = pattern.Matches(textElement.Content.Value);
                 foreach (Match match in matches)
                 {
                     variables.Add(match.Groups[1].Value.Trim());

src/FlexRender.Core/Layout/ApproximateTextShaper.cs

@@ -33,7 +33,7 @@ public TextShapingResult ShapeText(TextElement element, float fontSize, float ma
     {
         ArgumentNullException.ThrowIfNull(element);
 
-        if (string.IsNullOrEmpty(element.Content))
+        if (string.IsNullOrEmpty(element.Content.Value))
         {
             return new TextShapingResult(
                 Array.Empty<string>(),
@@ -43,16 +43,16 @@ public TextShapingResult ShapeText(TextElement element, float fontSize, float ma
 
         var charWidth = fontSize * CharWidthFactor;
         var lineHeight = LineHeightResolver.Resolve(
-            element.LineHeight,
+            element.LineHeight.Value,
             fontSize,
             fontSize * DefaultLineHeightMultiplier);
 
-        var effectiveMaxWidth = element.Overflow == TextOverflow.Visible && !element.Wrap
+        var effectiveMaxWidth = element.Overflow.Value == TextOverflow.Visible && !element.Wrap.Value
             ? float.MaxValue
             : maxWidth;
 
-        var lines = GetLines(element.Content, element.Wrap, effectiveMaxWidth, charWidth,
-            element.MaxLines, element.Overflow);
+        var lines = GetLines(element.Content.Value, element.Wrap.Value, effectiveMaxWidth, charWidth,
+            element.MaxLines.Value, element.Overflow.Value);
 
         if (lines.Count == 0)
         {