Add documentation to extend JSX typing

[elpupi]

Stencil version:

 @stencil/core@1.12.6

I'm submitting a:

[x] bug report
[x] feature request
[ ] support request => Please do not submit support requests here, use one of these channels: https://stencil-worldwide.herokuapp.com/ or https://forum.ionicframework.com/

Current behavior:

It is possible that they are missing JSX.IntrinsicElements definitions leading to jsx typing errors.
For instance, if one is willing to add the attribute xmlns-link in an svg element, typescript will emit the following error is not assignable to type 'SVGAttributes<SVGElement>.
It is not possible to consider all typings. Especially for specific use cases. A good solution is to extend the stencil JSX typing in an ambient declaration module as follow:

// anyname-you-wish.ts anywhere in the src directory
import { VNodeData, VNode, JSX as LocalJSX, JSXBase } from '@stencil/core/internal';

declare module '@stencil/core' {
    export namespace h {
        function h(sel: any): VNode;
        function h(sel: Node, data: VNodeData): VNode;
        function h(sel: any, data: VNodeData): VNode;
        function h(sel: any, text: string): VNode;
        function h(sel: any, children: Array<VNode | undefined | null>): VNode;
        function h(sel: any, data: VNodeData, text: string): VNode;
        function h(sel: any, data: VNodeData, children: Array<VNode | undefined | null>): VNode;
        function h(sel: any, data: VNodeData, children: VNode): VNode;
        namespace JSX {
            interface IntrinsicElements extends LocalJSX.IntrinsicElements, Omit<JSXBase.IntrinsicElements, 'svg' | 'div'> {
                svg: JSXBase.SVGAttributes<SVGElement> & { viewbox?: string; xmlnsXlink?: string; };
                div: JSXBase.HTMLAttributes<HTMLDivElement> & { field?: string; };
            }
        }
    }
}

Unfortunately, it is not documented anywhere and someone can struggle a lot to find out a way to make it work.

Furthermore, it is strange to be obliged to import a function not used in the code but injected during compilation. Wouldn't be nicer to add the import { h } from '@stencil/core' dynamically before ts is compiled and add the namespace h in an ambient global definition?

Expected behavior:
Extended JSX typing working.

Related code:

@Component({
    tag: 'svg-wrapper',
    shadow: true,
})
export class SvgWrapper implements ComponentInterface {
    render() {
        return (
            <svg width="24px" height="24px" viewbox="0 0 24 24" xmlns="http://www.w3.org/2000/svg" xmlnsXlink="http://www.w3.org/1999/xlink">
                <slot></slot>
            </svg>
        );
    }
}

[manucorporat]

Wouldn't be nicer to add the import { h } from '@stencil/core' dynamically before ts is compiled and add the namespace h in an ambient global definition?

Initial version of stencil didn't required to import the h() function and that was a mess, causing a lot of conflicts with other JSX implementation, since stencil components are designed to be consumed in angular, and react for example.

Unfortunately, it is not documented anywhere and someone can struggle a lot to find out a way to make it work.

Personally i never had to extend the types for custom attributes, seems like a bad idea? can you explain your use case more?
maybe a PR in https://github.com/ionic-team/stencil-site/blob/master/src/docs/components/templating-and-jsx.md

[elpupi]

Initial version of stencil didn't required to import the h() function and that was a mess, causing a lot of conflicts with other JSX implementation, since stencil components are designed to be consumed in angular, and react for example.

I get it. But for people using Stencil just to build web-components to be used natively in the browser without any framework, it is useless. Maybe there could be a config file to configure the way stencil generate behaves by default. It could be added few options like create scss file and not css, to disable test files generation, etc.

Personally i never had to extend the types for custom attributes, seems like a bad idea? can you explain your use case more?

I ended up writing a svg with attributes not declared in JSXBase.SVGAttributes. I was obliged to add them to comply a tool I am using. I imagine, people can end up in similar isolated circumstances. One can use Stencil for other purposes than for the web and so the attributes used can be whatever one wishes without being compliant to the HTML/SVG specs.

I think a PR to the components/templating-and-jsx documentation can be a good idea and I will do it.

[elpupi]

Here the opened issue #630 on ionic-team/stencil-site repo.

[erwinsmit]

@milottit I was also struggling with this when importing another component library like shoelace.

I solved it by adding a type declaration file like this:

import { JSX as CompLibraryJSX } from 'your-component-library';
import { JSX as StencilProjectJSX } from '../your-stencil-project-components';

type Omit<T, K> = Pick<T, Exclude<keyof T, K>>

type StencilProps<T> = { [P in keyof T]: Omit<T[P], "ref"> };

type CompLibraryComponents<
  T = CompLibraryJSX .IntrinsicElements,
> = StencilProps<T>;

type StencilProjectComponents<
T = StencilProjectJSX .IntrinsicElements,
> = StencilProps<T>;

declare module "@stencil/core" {
  export namespace JSX {
    interface IntrinsicElements extends CompLibraryComponents, StencilProjectComponents{}
  }
}

I used the code examples from this issue as an example:
#1636

[ionitron-bot]

Thanks for the issue! This issue is being closed due to inactivity. If this is still an issue with the latest version of Stencil, please create a new issue and ensure the template is fully filled out.

Thank you for using Stencil!