Expressions & Formatting

The expression language

Expressions appear in bindings (from:x, bind:x), handler steps (expr:value), structural directives, and inline text expressions ({expression}). A handler evaluates expr:value only when that step runs; from:x and <computed from> keep their dependencies live. Every root identifier must resolve through the template's declared binding scope: props, mutable and computed state, data, imports, loop locals. Handler expressions may additionally read their reserved triggering-event reference, $$event. Ambient JavaScript globals are not in scope. The browser evaluates a parsed tree; ahead-of-time targets compile the same tree. No eval(), no new Function(). The closest mainstream precedent is Angular template expressions, a restricted, AOT-compiled, non-eval subset; Alpine.js and Lit are the contrast, interpolating real JavaScript and inheriting the CSP hazard this avoids.⁹

<!-- Expressions look like this: plain reads, comparisons, and arithmetic. -->
<p $if="$user.isAdmin">…</p>                        <!-- a boolean guard -->
<progress from:value="$cart.items.length"></progress>  <!-- a bound value -->
{($price - $discount) * 1.08}     <!-- arithmetic, no filters -->

Scope & name resolution

A bare identifier resolves through the template's declared scope, never an ambient JavaScript global, and an identifier that resolves to nothing is a conformance error. Scope has two parts.

Identifier spelling and case

Expression identifiers are case-sensitive. A reference in an expression or through the JavaScript interface must use the declaration's exact spelling: $count and $Count read different names. Public props must not differ only in ASCII casing, because the HTML parser lowercases attribute names; <prop name="count"> and <prop name="Count"> cannot both be declared. Other scope names retain their case-sensitive identity.

An identifier starts with a CSS Syntax ident-start code point and continues with ident-start code points or ASCII digits.¹⁸ This reuses CSS's defined character repertoire, including _ and permitted non-ASCII characters, but not CSS identifier tokenization: dashes are not allowed at any position, and names have no escape sequences. $ is a reference marker, never part of a name. Thus _name, first_name, firstName, and name2 are identifiers; -name, --name, first-name, $name, and 1name are not identifier spellings. $first-$name is subtraction between two references. External keys outside this grammar remain accessible through a quoted bracket key, such as $record['first-name'].

The component layer is flat, and collisions are errors

A component's own declarations, <prop>, <state>, <computed>, <data>, and <context>, share one flat namespace. Each uses its name, except <context> uses as when supplied. Two declarations introducing the same local name are a conformance error, not a silent precedence: the author disambiguates rather than memorizing which kind wins. Each <data> is named, so datasets are referenced individually (search.value, orders.pending). A context name reads the provider's state with the same type and reactive behavior, but is read-only in this scope (see Reactivity).

Inner layers are lexical, and they shadow

$each, $with, $match, and scoped slots each push a lexical layer whose names are statically known. A bare identifier resolves in the nearest enclosing layer, walking outward to the component layer, so an inner layer shadows an outer one, because that is local and expected: a loop's item may shadow an outer item. Cross-layer shadowing is allowed; a collision within the flat component layer is not.

Reserved handler reference

$$event references the native event that invoked the current handler. It is reserved, cannot be declared or assigned, and is available only in that invocation's expressions and guards. Member access reads the native event's properties; it does not enable arbitrary method calls or ambient JavaScript access. Each nested handler invocation has its own event reference. See The triggering event for typed payload forwarding and storing selected fields.

Grammar

expr      := conditional                        (* no pipeline: there is no "|" filter *)
conditional := or ("?" expr ":" conditional)?    (* lowest precedence; associates right *)
or        := and ("or" and)*
and       := eq ("and" eq)*
eq        := cmp (("=" | "!=" | "^=" | "$=" | "*=") cmp)*
cmp       := add (("<" | "<=" | ">" | ">=") add)*
add       := mul (("+" | "-") mul)*
mul       := unary (("*" | "/" | "%") unary)*
unary     := ("not" | "-") unary | access
access    := primary (("." id) | ("." integer) | ("[" expr "]"))*
primary   := literal | dimension | reference | handler-reference | id | call | "(" expr ")" | object | array
handler-reference := "$$event"                  (* only within a handler invocation *)
reference := "$" id
id        := ident-start (ident-start | digit)*  (* CSS ident-start; no dashes or escapes *)
dimension := css-number css-unit | css-number "%" (* units from Types; no whitespace *)
integer   := digit+
call      := fn "(" (expr ("," expr)*)? ")"    (* fixed, typed, CSS-style — not arbitrary calls *)
fn        := "round" | "clamp" | "min" | "max" | "abs" | "default" | "concat" | "join" | "format" | "formatRange" | "formatParts"
object    := "{" (pair ("," pair)* ","?)? "}"
pair      := (id | string) ":" expr
array     := "[" (expr ("," expr)* ","?)? "]"

css-number is a finite CSS number token; css-unit is a unit accepted by length or duration in Types. A numeric token immediately followed by a known unit or % forms one dimensional literal before the parser considers the % remainder operator. Thus 25% is a percentage; 25 % 4 is remainder. Unary - negates a number or dimensional literal, so -2rem is a length. Binary operators follow the typed arithmetic rules below. Conventional precedence with parentheses applies. Equality, missing data, truthiness, and coercion are specified explicitly (see Value semantics, next) rather than inherited from JavaScript or any template language.

A $-prefixed name reads a declared value. A literal list index can be dotted or bracketed: $items.0.name and $items[0].name both read the first item's name and have the dependency path items.0.name, without the expression's $ reference marker. Directly written integer keys retain their exact spelling in either form, so $byId.9007199254740993 and $byId[9007199254740993] read the same object key without rounding it. Brackets also accept a computed key, such as $items[$index], or a quoted object key that cannot be written as a dot segment.

test ? yes : no tests the same truthiness as $if, evaluates only the selected branch, and returns that branch's value without coercion. It is for a small inline value choice, such as from:aria-current="$activeStep = $index ? 'step' : null"; use $match when whole markup differs. All three branches participate in static name and dependency checks.

Equality and string matching are spelled the way CSS attribute selectors already spell them. The language is assignment-free, so a single = means equal with nothing to disambiguate it from, and the selector match family carries over directly:

Value semantics

Equality, missing data, truthiness, and coercion are defined here explicitly, so nothing is inherited by accident from JavaScript or a template language. The whole model follows one platform instinct: the platform does not throw. CSS drops an invalid declaration and falls back; the HTML parser recovers from any malformed input. Absence is a value, not a crash.

The absent value

Reading a property that is not present at runtime, order.error.message when error is null, yields a single first-class absent value rather than an error, and further access on it is absent too, safe navigation everywhere. The absent value behaves consistently in every position: it renders as empty text, reads as false in a condition, and removes the attribute in from:attr position, exactly the serialization already defined for null/undefined (see Bindings). It also propagates: any operation with an absent operand is itself absent, the way an invalid value invalidates a whole CSS declaration⁷ and a SQL NULL propagates through an expression.

Truthiness: the empty value of each type is false

$if, $when, and and/or/not test truthiness by one rule, the empty value of each type is false, everything else true:

Empty values are false: no characters, no count, no items. This makes ordinary guards work without a length check: $if="$cart.items" hides on [], and $if="$unread.count" hides on 0. and, or, and not return a boolean rather than one of their operands. Fallback for absence is explicit (below), never a side effect of or.

Equality is typed; operators never coerce

Comparison is typed. Two values of different types are not equal, and comparing operands whose types are statically known to be disjoint, a number against a string literal, is a conformance error, a caught bug rather than a silent false. Where a type mismatch can only be known at runtime, the result is simply false; it never throws.

Arithmetic follows the operand types. + is not overloaded for string concatenation, so "1" + 1 can never silently become "11". An incompatible combination is a type error where it is statically known, and absent otherwise. Operators never coerce across types. Conversion happens at typed edges: a number prop converts its incoming string once, on the way in, the way <input> exposes both value and valueAsNumber, never mid-expression. The rules for dimensions give each valid operation a result type.

concat(value, …) is an explicit conversion edge for constructing a string. One argument converts an accepted scalar value to text; further arguments append their text in order. It does not bypass a declaration's type check. Its arguments and errors are defined under Functions.

Fallback for absence

Because or returns a boolean, fallback has an explicit form. default($user.name, 'friend') uses 'friend' when the value is absent or null; it preserves false, 0, and ''. The fallback is evaluated only when needed. This resembles CSS var(--x, fallback)⁷ and Jinja's undefined-only default¹⁰, with null included because an omitted optional prop resolves to null. {default($user.name, 'friend')} inserts that fallback result in text with the same absent-or-null trigger. A whole-markup choice among several states is a $match; a small value choice can use ? :.

Object & array expressions

The grammar includes object and array expressions for structured values. They resemble JSON and a JS object but are neither: an object expression is a production of this pure, typed language, evaluated deterministically with no eval(), whose values are ordinary expressions from this same grammar, not arbitrary JavaScript. In shape they are simply { [key: string]: Expression } and [...Expression], so they nest recursively: any value may itself be another object or array expression.

<state name="draft" type="object({ title: string, tags: list(string), done: boolean })"
       value="{ title: '', tags: [], done: false }">

<x-list rows="[{ id: 1, name: 'Ada' }, { id: 2, name: 'Lin' }]">

<!-- A computed object can read another declaration. -->
<computed name="filter" from="{ status: $currentStatus, limit: 10 }">

A declared structured prop or state can parse a fixed object or array from a plain attribute, as rows and draft do above. A from: binding or <computed from> evaluates an expression and updates when the values it reads change. A plain value attribute accepts literal contents.

Two rules keep them unambiguous, and both reuse positions defined elsewhere rather than inventing new ones:

• a key is attribute-position: a bare identifier and a quoted string are the same string key, so { open: … } equals { 'open': … };
• a value inside an expression may be a reference or a literal: { label: $name } reads name, while { label: name } contains the literal keyword name. A plain typed attribute, including <state value>, accepts only literal values.

Functions

Functions cover operations that an operator or an existing HTML/CSS feature does not express clearly. Their names are fixed; a component cannot register a callable function in an attribute. A call has no side effects and reads the same reactive dependencies as its arguments.

<computed name="snapped" from="round($width, 1px)"></computed>
<computed name="shown" from="default($count, 0)"></computed>
{format(($price - $discount) * 1.08, 'currency', { currency: 'USD' })}

round uses CSS's default nearest strategy: an exact halfway case goes toward positive infinity. Thus round(2.5) is 3 and round(-2.5) is -2. An omitted step rounds the numeric part of a dimensional value to a whole number in its current unit: round(8.8px) is 9px, round(25.5%) is 26%, and round(1.6s) is 2s. round(1600ms) remains 1600ms: the function rounds the value as written. CSS requires an explicit step for dimensions; this proposal makes it optional.⁶ A supplied step must use the same written unit, so round(8.8px, 1px) is valid and round(8.8px, 1rem) is invalid. A negative step has the same multiples as its positive magnitude; a step of zero has no result. Other CSS rounding strategies (up, down, to-zero) are not included in this level; adding them later will use CSS's leading strategy argument rather than changing the meaning of these calls.⁶

Values with units

The length, percentage, and duration types are strings at the JavaScript boundary, but they are typed quantities while an expression calculates with them. A literal such as 8.8px, 25%, or 200ms has that type. A reference declared as one of those types supplies its accepted numeric part and written unit to a calculation. The result crosses back to a prop, state, or DOM binding in the type's written form, such as 9px; it is not exposed as a JavaScript number. The HTML clock-time type time is not a CSS duration.

For a function with more than one dimensional argument, every argument must have the same type and the same written unit. min(1px, 2px) and min(1rem, 2rem) work; min(1in, 100px) and max(200ms, 0.5s) are invalid, even though CSS defines conversion ratios for those units.¹² The functions do not convert units or silently choose an output unit. abs has one argument, so abs(-2rem) simply returns 2rem. Percentages compare with percentages, never with lengths. Calculations that need unit conversion or layout and font context belong in a controller; CSS math remains available in CSS properties where that context exists.

<state name="width" type="length" value="8.8px"></state>
<computed name="snappedWidth" from="round($width, 1px)"></computed>
<!-- snappedWidth has type length and written value 9px. -->

<computed name="safeWidth" from="max($width, 1rem)"></computed>
<!-- If width is in px, no comparison is made: the written units differ. -->

Unitless 0 is a number, so round(8px, 0) is a type error; use 0px (which then fails as a zero step). The five math functions return number for numeric inputs, including integer inputs; an integer destination checks whether the result is whole at its typed edge.

Arithmetic with units

An integer or a fractional number is unitless. The result type follows the operands, then the destination checks whether that result is allowed. Each dimensional result retains its operand's written unit. CSS math's type checking is prior art, but these rules use only calculations that need no unit conversion.¹⁷

1px + 1 and 1px + 1ms are invalid because their types differ. 1px + 1rem is invalid because the written units differ. Multiplying two dimensions, dividing a number by a dimension, and dividing one dimension by another are not defined here, even when the written units match. A zero divisor or non-finite result from dimensional arithmetic is invalid. A compiler rejects a statically known invalid combination. At runtime, an invalid calculation does not write its destination: the destination keeps its last accepted value, or its default/null before any successful write, as described under invalid reactive results. An absent operand still produces absence, with its ordinary empty/removal behavior. An integer destination accepts a result only when it is whole.

<state name="width" type="length" value="100px"></state>
<computed name="quarterWidth" from="$width / 4"></computed>
<computed name="paddedWidth" from="$quarterWidth + 2px"></computed>
<!-- quarterWidth is 25px; paddedWidth is 27px. -->

If width then changes to 100rem, quarterWidth becomes 25rem, but paddedWidth keeps 27px: adding 25rem and 2px is invalid. When width changes back to 120px, paddedWidth updates to 32px.

Fallback and text assembly

default is lazy: it evaluates value first, and evaluates fallback only if that result is absent or null. Both arms must have the same declared type, or satisfy the same expected destination type; it does not create a mixed-type union. A present but invalid typed reference is not absence and cannot be rescued by default; the invalid result follows the live-binding rule: the destination keeps its last accepted value, or its default/null if it has never accepted one. The function does not use truthiness.

concat requires at least one argument. Each must be a scalar (string, keyword, boolean, integer, number, or a serialized scalar type such as length). It uses that type's normal attribute text: for example concat(true) returns 'true' and concat(8px) returns '8px'. A value keeps its normal type checks until it reaches this explicit text conversion. Missing data propagates as absent; null contributes an empty string. Lists and objects are not concat arguments. Locale-sensitive number, date, currency, and list presentation uses the Intl formatting functions below. XPath supplies the function's name and ordered concatenation, but Declarative Components also permits one argument so the same function can replace format('%s', value) without another conversion function.¹¹

join requires exactly two arguments: a list and a string separator. The list may be empty and must have one scalar item type, as described in Types. Items use the same text conversion as concat; a null item contributes an empty string, but still occupies its position between separators. An empty list returns '', and a one-item list returns that item's text without a separator. An absent list, separator, or item propagates as absent. An object item or a separator of another type makes the call invalid. For example, join(['red', null, 'blue'], ', ') returns 'red, , blue', while join([], ', ') returns ''. This function assembles an attribute or computed string; format($items, 'list') is the locale-sensitive way to present a list to readers.¹⁶

Invalid calls and live bindings

Wrong argument counts, incompatible types or units, a zero rounding step, and a non-finite numeric result make the call invalid. A compiler reports a statically knowable mistake. The browser runtime reports an authored-definition mistake once, but does not throw or warn for an ordinary user edit that makes an input invalid. At runtime an invalid call does not write a bound destination: it keeps the last accepted result, or the declared default/null if no result was accepted. This is the same sequence as any other invalid live expression; it does not replace the destination with a string containing the invalid input.¹³

<prop name="amount" type="number" default="5"></prop>
<computed name="bounded" from="clamp(0, $amount, 10)"></computed>
<!-- amount 2 → bounded 2; then invalid input "oops" → bounded stays 2. -->
<!-- If the first input is invalid, amount and bounded begin from default 5. -->

Why this set

The admission test for a built-in is concrete: it must express a recurring typed operation that an operator, element, or CSS property does not already express at that use site; it must be pure; and both the browser interpreter and compiled targets must be able to give it the same result. round($width, 1px) passes because a computed length may feed a prop or attribute, not just a CSS property. concat($progress, '%') passes because + is numeric-only and a live attribute may need a string. join($tags, ', ') assembles a list for an attribute with a chosen separator. Locale presentation uses format() below, so it works in computed values and bindings as well as displayed text.

Template languages show a need for transformations but disagree on what a broad library should contain. Liquid and Twig supply dozens of filters, including arithmetic and formatting; Jinja supplies a configurable filter library. Angular pipes cover locale formatting and arbitrary presentation transformations, while Vue 3 removed its template filters.¹⁴ Handlebars and Mustache show a smaller expression surface but rely on helpers or lambdas for custom work.¹⁵ Declarative Components places the recurring jobs where its existing syntax already puts them:

join() uses an author-chosen separator; format($names, 'list') assembles a list using locale rules. Both return strings for any expression destination. Space- and comma-separated typed attributes also have their own written forms, so they do not need join just to parse a list.

This keeps the browser interpreter and generated Vue/React expressions deterministic. It also avoids silently choosing a different fallback rule from Liquid or Twig, both of which replace some present false or empty values.¹⁰

Formatting: Intl expressions

Locale-aware formatting is a fixed expression operation backed by the Intl formatters.⁴ It returns escaped text when used in template output, and the same result can feed an attribute, prop, handler step, or computed value. Options use the native case-sensitive camelCase names, such as currencyDisplay, timeStyle, and maximumFractionDigits.

format(value, options?, locale?)
format(value, formatter, options?, locale?)
formatRange(start, end, options?, locale?)
formatRange(start, end, formatter, options?, locale?)
formatParts(value, options?, locale?)
formatParts(value, formatter, options?, locale?)

An object in the options position selects inferred formatting; a string in the formatter position selects an explicit formatter. To supply only a locale override, write an empty options object: format($amount, {}, 'fr-CA'). A locale is a BCP 47 language tag, with an optional region, and may itself be an expression. Omission uses the execution environment's default locale. Currency and time zone remain independent options. SSR must receive the same explicit locale and, for instants, time-zone options as the browser when identical initial text is required; a server cannot infer the browser's preferences.

Explicit formatters

The explicit numeric presets set the native style; a conflicting authored style is invalid. Other options are delegated to the selected native constructor, including its defaults, accepted combinations, and treatment of unknown option names. HTML Next does not add a second options schema or rename the native options.

<p>Total: {format($cart.total, 'currency', { currency: 'USD' })}</p>
<p>Published: {format($publishedAt, 'date', { dateStyle: 'long' })}</p>
<p>Updated: {format($minutesAgo, 'relativeTime', { unit: 'minute' })}</p>
<p>Guests: {format($names, 'list', { type: 'conjunction' }, $locale)}</p>
<output>{format($elapsed, 'duration', { style: 'digital' })}</output>
<computed name="priceLabel" from="format($price, 'currency', { currency: 'CAD' }, 'fr-CA')"></computed>

Inference follows the declared type

Each supported type has one default formatter. Inference never parses an ordinary string to guess its meaning, and never guesses a formatter from option names. Constraints do not change the underlying formatting identity. Nullable unions ignore absence; other union members must agree on one identity. A selected type can infer only when all possible selections agree. An ordinary string, unknown value, or conflicting union requires an explicit formatter.

Numeric expression literals and arithmetic also have their numeric or dimensional identity. Known string-list literals infer list. Typed nested paths and lexical aliases retain their declared identity. An untyped computed declaration needs an explicit formatter when its result's identity is unavailable at the use site.

// These pairs are equivalent for the corresponding declared types.
format($clock, { timeStyle: 'long' })
format($clock, 'time', { timeStyle: 'long' })

format($amount, { style: 'currency', currency: 'USD' })
format($amount, 'currency', { currency: 'USD' })

// Generic options may be clearer with an explicit formatter.
format($names, 'list', { style: 'long' })
format($elapsed, 'duration', { style: 'long' })

Inference is a convenience, not a promise that every shorthand is readable without its declaration. Authors can always make intent visible with an explicit formatter.

Typed values and native input

date, time, and datetime-local are civil values without a time zone. Formatting must preserve their calendar and clock fields without shifting them to the machine's zone or inventing a zone label. The JavaScript adapter uses an internal UTC anchor and removes zone-name parts from long or full time styles. Explicit timeZone or timeZoneName options on those zone-free values are invalid. A datetime is an instant; it uses the selected native time zone. An explicit date/time formatter also accepts HTML date/time strings or numeric epoch milliseconds. A date-only input cannot supply clock fields, and a time-only input cannot supply calendar fields. Invalid dates must not roll over into another calendar day.

A typed CSS percentage such as 15% supplies the ratio 0.15 to number formatting. A typed CSS duration such as 1500ms supplies a balanced hours/minutes/seconds/subseconds record; signs are preserved. A structured duration record passes its fields to Intl unchanged. These adapters preserve type meaning rather than treating every serialized value as an ordinary string.

Plural messages

plural selects one of the CLDR categories zero, one, two, few, many, or other using Intl.PluralRules, then selects the corresponding string from forms. other is required and supplies the fallback. Every # in that selected string is replaced with the number formatted in the same locale and precision. This is a small message-selection operation layered on Intl, rather than an assertion that Intl itself interpolates messages.⁵

format($count, 'plural', { forms: { one: '# item', other: '# items' } })
format($position, 'plural', {
  type: 'ordinal',
  forms: { one: '#st', two: '#nd', few: '#rd', other: '#th' }
}, 'en')

Ranges, parts, and invalid results

formatRange() uses native number or date/time range formatting. Both ends must be valid inputs for the selected formatter. formatParts() returns native structured parts for number, date/time, relative-time, list, or duration formatting, so markup can style individual pieces. It is not supported for display names or plural messages. Civil date/time parts omit invented zone names.

<p>{formatRange($minimum, $maximum, 'currency', { currency: 'USD' })}</p>
<span $each="part of formatParts($price, 'currency', { currency: 'USD' })">{$part.value}</span>

Absence or null produces absence. An invalid input, formatter, argument count, native option combination, locale, or unsupported operation produces the existing invalid built-in result: no destination write, retaining the last accepted value. Formatted strings remain data, never a second round of HTML or template parsing. A JavaScript host without a selected Intl facility requires a conforming polyfill; an unavailable facility produces the same invalid result. Native locale data can vary across engine and ICU versions; the reference targets share the same adapter and preserve the selected platform semantics.

Reactive dependencies

A parsed expression exposes exactly which paths it reads, so dependencies are statically known. $subtotal, $discount, and $rate in ($subtotal - $discount) * $rate are all discoverable without runtime tracking: the browser subscribes to those paths, and each framework target translates them to its own reactive model. See Reactivity.

References

1. CSS Selectors Level 4, attribute selectors ([a=b], ^=, $=, *=).
2. XPath, XML Path Language 3.1 (the != inequality).
3. CSS Media Queries Level 4, range context (< <= > >=).
4. ECMAScript Internationalization API, ECMA-402 (the Intl formatters).
5. Unicode LDML, MessageFormat; CLDR plural categories.
6. CSS Values and Units Level 4, math functions (calc/clamp/min/max/round).
7. CSS Custom Properties Level 1, the guaranteed-invalid value and var() fallback (absence propagates; fallback triggers only on absence).
8. WHATWG HTML, parse errors and recovery (the parser never aborts; the fault-tolerance model the runtime follows).
9. Angular template expressions: a deliberately restricted, AOT-compiled, non-eval subset, the closest mainstream precedent to an expression language that is not JavaScript in a string. Contrast (do not inherit): Alpine.js x-data expressions and Lit template expressions both interpolate real JavaScript, the CSP hazard HTML Next avoids.
10. Jinja default filter uses an undefined-only fallback unless explicitly told to include false values. Liquid default and Twig default also replace some present false or empty values; Declarative Components does not.
11. XPath and XQuery Functions and Operators 3.1 defines string concat() for two or more atomic values. This proposal also permits one argument for explicit scalar-to-string conversion. Liquid's different concat filter joins arrays; this proposal uses the XPath string meaning.
12. CSS Values and Units Level 4 defines absolute length ratios, relative lengths, percentages, and time units.
13. Reactivity specifies that an invalid live expression leaves the destination at its last accepted value, or its initial default/null.
14. Liquid filters, Twig filters, Jinja filters, Angular pipes, and the Vue 3 filter removal show the range of template transformation designs.
15. Handlebars built-in helpers and Mustache sections and lambdas show smaller core syntax with extension points for custom behavior.
16. XPath and XQuery Functions and Operators 3.1 defines string-join; Twig joins sequences, and Liquid has a join filter.
17. CSS Values and Units Level 4, math function type checking, derives calculation types from operands. Declarative Components adopts only the operations listed above and does not convert written units.
18. CSS Syntax Module Level 3, ident-start code point. Only the character definition is reused; the leading-dash and escape rules of CSS identifier tokenization do not apply.