[docs] Add documentation for using PFElements in React+TypeScript projects

[mwcz]

I'm currently putting a PFElement-based component into a React project written in TypeScript. Adding PFElements to standard React is easy (Kyle has gone from no project, to a React project with a PFElement in less than 3 minutes), but TypeScript complicates things a bit.

So far, I've run into two things that need to happen to make a PFElement work seamlessly in React+TS.

1. add the element name to the JSX.IntrinsicElements interface

declare global {
  namespace JSX {
    interface IntrinsicElements {
      'rh-edmund-abbott': EdmundAbbottProps;
    }
  }
}

2. create a type representing the attributes of the element

interface EdmundAbbottProps extends React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> {
  product: string;
  version: string;
}

I don't have it all figured out yet. For example, in step 1, TS complains about augmenting the global scope outside the root module (which is App.tsx in this case).

We may also need to provide a .d.ts file containing all the type definitions. I'm guessing the code from step 2 would belong in that file, and perhaps other type definitions as well?

@KamiQuasi may have feedback here!

[castastrophe]

cc @Djfaucette and @zhawkins who have some React experience too and might have ideas/thoughts

[Djfaucette]

I'm also using PFElements in a TypeScript app and the following is all I had to add to my declarations.d.ts file:

declare namespace JSX {
  interface IntrinsicElements {
    "pfe-card": any;
    "pfe-cta": any;
    "pfe-datetime": any;
    etc...
  }
}

Essentially we want the JSX engine to recognize all of those strings as valid HTML/XML, so adding it to an interface works.

We could, maybe, be more specific with the typings we give to tags, but at this stage of the game (not using TypeScript anywhere in our project) don't know that we would have a way to track that effectively as attributes evolve over time.

[castastrophe]

Is there anything that a component can offer that would help with this for users or is it a case of needing more documentation?

[Djfaucette]

I think we need more docs either way. I can't think of a straightforward solution, but it's probably worth taking a look at component libraries that use TypeScript for some inspiration.

[mwcz]

89 can help with this, typescript can create d.ts files based on JSDoc comments in JS codebases.

[bennypowers]

We can add this to https://github.com/patternfly/patternfly-elements/blob/58b1ae602790a4532c9dc485c2f8bb36f81a1d44/docs/framework-integration/react.md