Merge pull request #69 from sw-yx/document-types-react

document @types/react

ADVANCED.md

@@ -16,6 +16,7 @@
 - [Section 1: Reusable Components/Type Utilities](#section-1-reusable-componentstype-utilities)
   * [Higher Order Components](#higher-order-components-hocs)
   * [Render Props](#render-props)
+  * [`as` props (passing a component to be rendered)](#as-props-passing-a-component-to-be-rendered)
   * [Types for Conditional Rendering](#types-for-conditional-rendering)
   * [Props: One or the Other but not Both](#props-one-or-the-other-but-not-both)
   * [Props: Must Pass Both](#props-one-or-the-other-but-not-both)
@@ -36,6 +37,7 @@
   * [Prettier + TSLint](#prettier--tslint)
   * [ESLint + TSLint](#eslint--tslint)
   * [Working with Non-TypeScript Libraries (writing your own index.d.ts)](#working-with-non-typescript-libraries-writing-your-own-indexdts)
+- [Section 4: @types/react and @types/react-dom APIs](#section-4-typesreact-and-typesreact-dom-apis)
 </details>
 
 # Section 1: Advanced Guides
@@ -179,6 +181,19 @@ export interface Props {
 
 [Something to add? File an issue](https://github.com/sw-yx/react-typescript-cheatsheet/issues/new).
 
+## `as` props (passing a component to be rendered)
+
+`ReactType` is pretty useful to cover most types that can be passed to createElement e.g.
+
+```tsx
+function PassThrough(props: { as: ReactType<any> }) {
+   const { as: Component } = props;
+
+   return <Component />
+}
+```
+
+[Thanks @eps1lon](https://github.com/sw-yx/react-typescript-cheatsheet/pull/69) for this
 
 ## Typing a Component that Accepts Different Props
 
@@ -769,6 +784,63 @@ We have more discussion and examples [in our issue here](https://github.com/sw-y
 
 </details>
 
+# Section 4: @types/react and @types/react-dom APIs
+
+The `@types` typings export both "public" types meant for your use as well as "private" types that are for internal use.
+
+## `@types/react`
+
+[Link to `.d.ts`](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/react/index.d.ts)
+
+**Namespace: React**
+
+Most Commonly Used Interfaces and Types
+
+- `ReactNode` - anything that is renderable *inside* of JSX, this is NOT the same as what can be rendered by a component!
+- `Component` - base class of all class-based components
+- `PureComponent` - base class for all class-based optimized components
+- `FC`, `FunctionComponent` - a complete interface for function components, often used to type external components instead of typing your own
+- `CSSProperties` - used to type style objects
+- all events: used to type event handlers
+- all event handlers: used to type event handlers
+- all consts: `Children`, `Fragment`, ... are all public and reflect the React runtime namespace
+
+Not Commonly Used but Good to know
+
+- `Ref` - used to type `innerRef`
+- `ReactType` - used for higher order components or operations on components
+- `ComponentType` - used for higher order components where you don't specifically deal with the intrinsic components
+- `ReactPortal` - used if you specifically need to type a prop as a portal, otherwise it is part of `ReactNode`
+- `ComponentClass` - a complete interface for the produced constructor function of a class declaration that extends `Component`, often used to type external components instead of typing your own
+- `JSXElementConstructor` - anything that TypeScript considers to be a valid thing that can go into the opening tag of a JSX expression
+- `ComponentProps` - props of a component
+- `ComponentPropsWithRef` - props of a component where if it is a class-based component it will replace the `ref` prop with its own instance type
+- `ComponentPropsWithoutRef` - props of a component without its `ref` prop
+- all methods: `createElement`, `cloneElement`, ... are all public and reflect the React runtime API
+
+[@Ferdaber's note](https://github.com/sw-yx/react-typescript-cheatsheet/pull/69): I discourage the use of most `...Element` types because of how black-boxy `JSX.Element` is. You should almost always assume that anything produced by `React.createElement` is the base type `React.ReactElement`.
+
+**Namespace: JSX**
+
+- `Element` - the type of any JSX expression
+- `LibraryManagedAttributes` - used to resolve static `defaultProps` and `propTypes` with the internal props type of a component
+- `IntrinsicElements` - every possible built-in component that can be typed in as a lowercase tag name in JSX
+
+**Don't use/Internal/Deprecated**
+
+Anything not listed above is considered an internal type and not public. If you're not sure you can check out the source of `@types/react`. The types are annotated accordingly.
+
+- `SFCElement`
+- `SFC`
+- `ComponentState`
+- `LegacyRef`
+- `StatelessComponent`
+
+## `@types/react-dom`
+
+To be written
+
+
 # My question isn't answered here!
 
 - [File an issue](https://github.com/sw-yx/react-typescript-cheatsheet/issues/new).