Skip to content

Declare trigger API and element initializer JavaScript as snippets #26668

Description

@totally-not-ai

Describe your motivation

Part of #26151. The trigger API (component/trigger/internal/*, around 15 action, input and trigger classes) and ElementJsInitializerRegistration build client-side code with JsFunction.of(…), which the client compiles at runtime and which needs unsafe-eval under a strict CSP.

Describe the solution you'd like

Replace JsFunction.of(…) strings in these classes with declared snippets, keeping the public trigger API unchanged. Blocked on #25870.

Activity

  1. totally-not-ai commented on Oct 24, 2026

    @totally-not-ai
    ContributorAuthor

    Triage: this is a valid internal improvement, but it can't be implemented yet. It depends on #25870, which is still open. Nothing in the codebase provides JsSnippet, @JsParams or JsSnippets.of(…) yet, so the JsFunction.of(…) call sites have nothing to migrate to.

    Current state on main

    • There are 24 JsFunction.of(…) call sites in flow-server/src/main. Almost all of them are in component/trigger/internal/*: LiteralInput, PropertyInput, HandlerInput, SignalInput, ImageBlobInput, DownloadHandlerInput, CallbackAction, SetPropertyAction, PromiseAction, ShareAction, OpenInNewTabAction, DownloadAction, RequestFullscreenAction, WriteToClipboardAction and SizeTrigger. The remaining one is in ElementJsInitializerRegistration.
    • Each of these strings reaches the client as a JsFunction parameter. The client compiles it with new Function, so it needs unsafe-eval.

    Things to sort out when #25870 lands

    1. Nested snippets. An action captures its input's JsFunction as an argument, e.g. CallbackAction: $0($1(event)), and SetPropertyAction: $0[$1] = $2(event). SetPropertyAction then passes the action into Trigger.install(JsFunction). So a declared snippet must be able to take another declared snippet as a captured argument and invoke it on the client. Declare deferred JavaScript as JsSnippet so DOM listener expressions and Lit templates work without unsafe-eval #25870 describes JsFunction becoming a JsSnippet subtype passed as a parameter (see Use @JsDefinition also for creating JsFunction instances #25837), which should cover this. Worth checking explicitly when that is implemented.

    2. Expressions built at runtime have to become fixed.

      • ShareAction builds navigator.share({title:…, text:…, url:…}) from only the slots that are set.
      • OpenInNewTabAction concatenates JAVASCRIPT_SCHEME_JS_GUARD into its expression.
      • DownloadAction and RequestFullscreenAction pick between two expression strings.

      Each of these needs a single declared snippet (or a small fixed set) that takes nullable arguments, instead of string building.

    3. ElementJsInitializerRegistration is only partly fixable.

      • The framework wrapper (INIT_EXPRESSION / DISPOSE_EXPRESSION) can become a declared @JsExpression.
      • The user expression comes from the public Element.addJsInitializer(String, Object...). It stays a string compiled on the client.
      • DomEventTrigger and TimeoutTrigger install themselves through that same string API.

      So making triggers CSP-safe needs one of these:

      • (a) an internal install path that takes a declared snippet, or
      • (b) a new public overload such as addJsInitializer(JsFunction/JsSnippet, …).

      (b) is a public API decision and should be made together with Declare deferred JavaScript as JsSnippet so DOM listener expressions and Lit templates work without unsafe-eval #25870. The string overload can't be removed. It stays the escape hatch for application code, so under strict CSP it will still report, which is expected.

    4. The public trigger API stays unchanged. All affected classes are in …trigger.internal, so this can be done without touching public API, apart from the addJsInitializer question in 3.

    Suggested approach once unblocked

    • Add one @JsDefinition interface per area (inputs, actions, triggers), with JsFunction-returning @JsExpression methods. Use @JsParams("event") for the ones that currently use .withArguments("event").
    • Replace each JsFunction.of(…) with a call to that interface.
    • Install triggers through the snippet-accepting initializer path from point 3.
    • Cover it with the existing trigger unit tests, plus the planned strict report-only CSP integration test from Migrate Flow's remaining server-initiated JavaScript to declared JavaScript #26151.

    Leaving this open and blocked on #25870. No PR for now.

  2. added theissue type on Oct 26, 2026
  3. mcollovati commented on Nov 6, 2026

    @mcollovati
    Collaborator

    @totally-not-ai this ticket should not be blocked anymore

  4. totally-not-ai commented on Nov 6, 2026

    @totally-not-ai
    ContributorAuthor

    @mcollovati Thanks, confirmed: #25870 is closed, and main now has @JsDefinition / @JsExpression, JsSnippet, JsSnippets.of(…), @JsCalledWith and JsFunction.ofDeclaredCall(…), already used by #26699 and #26865. Most of this ticket can now move to that pattern without touching any public trigger API.

    One decision is still needed before I start: how triggers install their JavaScript. DomEventTrigger, TimeoutTrigger and SizeTrigger go through the public Element.addJsInitializer(String, Object...), and ElementJsInitializerRegistration turns that string into JsFunction.of(expression, parameters). That string is always compiled in the browser, so declaring every action and input as a snippet still leaves triggers needing unsafe-eval. There are three ways to handle it:

    1. Internal install path (no API change). ElementJsInitializerRegistration also accepts a ready-made JsFunction, and the trigger classes reach it through an internal helper. The init and dispose wrappers become a @JsDefinition. Public addJsInitializer(String, …) keeps compiling its string, which is expected for application-supplied JavaScript.
    2. Public overload Element.addJsInitializer(JsFunction initializer), where the initializer is a declared snippet. Triggers use it, and so can Clipboard (also a production addJsInitializer user, not listed in Migrate Flow's remaining server-initiated JavaScript to declared JavaScript #26151) and application code. This adds public API.
    3. Option 1 now, option 2 as a separate feature if there is demand for CSP-safe initializers in application code.

    I recommend 3: this ticket stays an internal refactor that is easy to review and revert, and the public overload gets its own API discussion.

    Proposed scope, either way:

    • Inputs and actions get one @JsDefinition of snippets, with @JsCalledWith("event") where the function takes the event. Composition such as $0($1(event)) works because a declared JsFunction can be captured by another one.
    • ShareAction, OpenInNewTabAction, DownloadAction, RequestFullscreenAction and WriteToClipboardAction currently build or pick their JavaScript at runtime. Each one gets fixed snippets that take nullable arguments, or one snippet per variant.
    • The JavaScript each trigger runs stays the same. Existing trigger tests cover the behaviour, and the classes that assert on expression strings move to asserting the declared call.

    Reply with the option you prefer and I will open a PR.

  5. mcollovati commented on Nov 6, 2026

    @mcollovati
    Collaborator

    @totally-not-ai Trigger API is still internal stuff. Go with option 3

  6. totally-not-ai commented on Nov 6, 2026

    @totally-not-ai
    ContributorAuthor

    @mcollovati Done with option 3: #26889 (draft).

    • The trigger inputs, actions and installers are declared in a new internal TriggerJs snippet definition, so wiring a trigger no longer compiles JavaScript in the browser.
    • Triggers install through a new ElementJsInitializerRegistration(StateNode, JsFunction) constructor, and its init/dispose wrappers are now declared calls. The public addJsInitializer(String, …) is unchanged and still compiles the application's expression.
    • The public snippet overload of addJsInitializer is left for a separate change, and Clipboard's paste handler still uses the string variant.
  7. moved this from 🟢Ready to Go to ⚒️ In progress in Vaadin Flow | Hilla | Kits ongoing workon Nov 12, 2026
  8. added 2 commits that reference this issue on Nov 13, 2026
    96e69ab
    6e38c30
  9. vaadin-bot commented on Nov 16, 2026

    @vaadin-bot
    Collaborator

    This ticket/PR has been released with Vaadin 25.4.0-alpha7.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Type

Projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions