bug: Incorrect TypeScript typings for JSX

[maxpatiiuk]

Prerequisites

• I have read the Contributing Guidelines.
• I agree to follow the Code of Conduct.
• I have searched for existing issues that already report this problem, without success.

Stencil Version

4.12.0

Current Behavior

It appears that the TypeScript definitions for JSX support in Stencil are not completely correct, and are causing issue when used with third-party tools (like @typescript-eslint)

Expected Behavior

JSX.Element type is resolved correctly

System Info

System: node 20.11.0
    Platform: darwin (23.2.0)
   CPU Model: Apple M1 Pro (10 cpus)
    Compiler: /Users/mak13180/site/esri/arcgis-web-components/node_modules/@stencil/core/compiler/stencil.js
       Build: 1705333241
     Stencil: 4.10.0 🍪
  TypeScript: 5.3.3
      Rollup: 2.42.3
      Parse5: 7.1.2
      jQuery: 4.0.0-pre
      Terser: 5.26.0

Steps to Reproduce

I made a small reproduction case based on the JSX typings in Stencil: source

See the error on line 16
Further, see that see that typescript compiler resolves the type as "error":

out.mp4

This is because TypeScript is hardcoded to look for Element type/interface in the JSX namespace
In the above demo, uncomment line 8 (not present in Stencil's typings), and see how the typescript compiler now correctly resolves the JSX type, and also the typescript-eslint error is resolved

Code Reproduction URL

• Initial problem: ESLint Playground - Example 1: "Unsafe return of an any typed value."
• After setting type Element = VNode in JSX namespace: ESLint Playground - Example 2: "'Fragment' cannot be used as a JSX component.
  Its return type 'VNode | VNode[]' is not a valid JSX element."
• Stencil Component Starter Reproduction

Additional Information

For reference, here are examples of Elements interface/type being included in the JSX element in other popular libraries:

• React - https://github.com/DefinitelyTyped/DefinitelyTyped/blob/6d0e970598392a8c1c62019150e4f197fadf301c/types/react/jsx-runtime.d.ts#L5
• PReact - https://github.com/preactjs/preact/blob/49433b3a16a629db3a9a39df3f9f81ff703078bb/src/jsx.d.ts#L41
• dom-expressions (used by SolidJS and others) - https://github.com/ryansolid/dom-expressions/blob/eb9a6bcf640b04c1d1c889d9983914a2776093fe/packages/dom-expressions/src/jsx.d.ts#L12
• Qwik - https://github.com/BuilderIO/qwik/blob/408576e8a2e1d11fabf030f37b5941c0a3274669/packages/qwik/src/core/render/jsx/types/jsx-qwik.ts#L7

After debugging typescript-eslint and reading TypeScript source code, it appears that TypeScript is hardcoded to look for JSX.Element type/interface, rather than look at the return type of the jsxFactory:

    function getJsxElementTypeAt(location: Node): Type {
        return getJsxType(JsxNames.Element, location);
    }

(TS 3.7 source)

out.mp4

[maxpatiiuk]

These types appear incorrect too:

export declare const Host: FunctionalComponent<HostAttributes>;
export declare const Fragment: FunctionalComponent<{}>;

because FunctionalComponent is defined as returning VNode | VNode[], but TypeScript expects Fragment to be equal to JSX.Element (thus just VNode, not VNode | VNode[])

export interface FunctionalComponent<T = {}> {
    (props: T, children: VNode[], utils: FunctionalUtilities): VNode | VNode[];
}

otherwise, the user of Stencil would be forced to specify return type as VNode | VNode[] everywhere in there application (i.e as render() return type)

and you get this TypeScript error:

'Host' cannot be used as a JSX component.
  Its return type 'VNode | VNode[]' is not a valid JSX element.ts(2786)

/// and:

'Fragment' cannot be used as a JSX component.
  Its return type 'VNode | VNode[]' is not a valid JSX element.
    Type 'VNode[]' is missing the following properties from type 'VNode': $flags$, $tag$, $elm$, $text$, $children$ts(2786)

something like this fixes it:

export declare const Host: (props:HostAttributes)=>VNode;
export declare const Fragment: (props: {})=> VNode;

[rwaskiewicz]

@maxpatiiuk Thanks! Someone will take a look at this in a bit.

Can you do me a favor and split #5306 (comment) into its own issue? I'd like to make sure we're not trying to understand two different Stencil issues in the context of one GitHub issue. Thanks!

[maxpatiiuk]

Can you do me a favor and split #5306 (comment) into its own issue? I'd like to make sure we're not trying to understand two different Stencil issues in the context of one GitHub issue. Thanks!

unfortunately, these fixes have to be in the same PR.

reason:

The problem is that adding the type Element = VNode; uncoverts the typing issues with Fragment/Host return type, causing TypeScript errors:

'Fragment' cannot be used as a JSX component.
  Its return type 'VNode | VNode[]' is not a valid JSX element.
    Type 'VNode[]' is missing the following properties from type 'VNode': $flags$, $tag$, $elm$, $text$, $children$ts(2786)

basically, we defined that JSX.Element is VNode, but return type of Fragment is not VNode but VNode | VNode[], so TypeScript complains. The other solution is to define type Element = VNode | VNode[]; but that is a bad idea (would force users of Stencil to always type the returns of their render() functions as VNode | VNode[] instead of just VNode)

(this is a limitation of TypeScript, see DefinitelyTyped/DefinitelyTyped#20544 and microsoft/TypeScript#21699)

so, while I could separate the PRs, they would have to be merged at the same time to avoid issues

[rwaskiewicz]

Hey! So while that context is helpful, what I was looking for a actually a separate issue, rather than PR. Specifically, I am looking for steps to reproduce the statements that Host and FunctionalComponent are incorrect. I'd like to understand where/how the errors you're showing in this comment are coming from (be it the output of stencil build, in an editor, a combination of both, etc.).

Prior to your second comment, it wasn't clear these were related. I still haven't dug in, but if you can let me know where how you're seeing these errors after applying that type Element = VNode change, that'd be a big help 👍

[maxpatiiuk]

Ah, thank you for the clarification - I misread your comment
Opened an issue, with the smallest reproducible code sample and a suggested fix - #5311