Skip to content

feat: add strict literal event arguments in fast declarative syntax #7567

Description

@janechu

🙋 Feature Request

Add WebUI-style strict event argument parsing and literal argument support to @microsoft/fast-html declarative event bindings. This would let developers pass repeat-scope values, literal values, $e, and $c predictably, while surfacing malformed handler syntax during template processing instead of silently normalizing it.

🤔 Expected Behavior

Declarative event bindings should resolve supported argument kinds consistently from the active template scope. For example, inside an <f-repeat> body:

<f-repeat value="{{item in items}}">
    <button @click="{$c.parent.selectItem(item.id, 'static', 1, true, null, $e)}">
        {{item.name}}
    </button>
</f-repeat>

The handler should receive the current item.id, the literal string/number/boolean/null values, and the DOM event object. Invalid or ambiguous syntax such as trailing commas, unclosed strings, extra text after the function call, invalid handler names, or invalid path tokens should fail clearly during template parsing.

Existing supported forms should continue to work, including $e, $c, $c.event, binding paths such as item.id, and the deprecated bare e warning path until that compatibility is removed.

😯 Current Behavior

fast-html already supports $e, $c, $c.somePath, and arbitrary binding paths as event arguments, including paths resolved from an <f-repeat> scope. However, parseEventArgs() currently splits on commas, filters empty tokens, and treats unrecognized tokens as binding paths.

That means literal arguments like 'static', 1, true, and null are resolved as data-source paths rather than literal values, and malformed argument lists can be silently normalized instead of rejected. Developers must currently move constants into component state or hard-code them inside the handler implementation.

💁 Possible Solution

Adopt a stricter, quote-aware event argument parser similar to the contract introduced in microsoft/webui#317 and tightened in microsoft/webui#322:

  • Parse event arguments into explicit descriptors for event, context, binding path, string, number, boolean, and null literals.
  • Reject malformed syntax instead of filtering empty or invalid tokens.
  • Preserve the existing deprecated bare e warning behavior while $e remains the preferred event argument.
  • Add fast-html unit and fixture coverage for repeat-scope path arguments, literal arguments, malformed input, and hydration behavior.

🔦 Context

microsoft/webui#317 added event handler arguments that resolve against repeat scopes, and microsoft/webui#322 tightened that behavior by making event argument metadata strict and adding literal support. FAST's @microsoft/fast-html declarative runtime already covers the repeat-scope path portion, but not the literal argument and strict parsing parts of that contract.

I searched open and closed issues in microsoft/fast for overlapping requests around parseEventArgs, strict event arguments, malformed event syntax, literal event arguments, and f-repeat event arguments and did not find a duplicate.

💻 Examples

<f-repeat value="{{item in items}}">
    <button @click="{$c.parent.selectItem(item.id, 'from-list', $e)}">
        {{item.name}}
    </button>
</f-repeat>
selectItem(id: string, source: string, event: Event) {
    // id is the current repeat item id, source is the literal string,
    // and event is the DOM event object.
}

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions