Fix content/en/guide/v10/typescript.md

content/en/guide/v10/typescript.md

@@ -5,17 +5,17 @@ description: "Preact has built-in TypeScript support. Learn how to make use of i
 
 # TypeScript
 
-Preact ships TypeScript type definitions, which are used by the library itself! 
+This guide explains how to configure to use Typescript and use Preact's TypeScript type definitions.
 
-When you use Preact in a TypeScript-aware editor (like VSCode), you can benefit from the added type information while writing regular JavaScript. If you want to add type information to your own applications, you can use [JSDoc annotations](https://fettblog.eu/typescript-jsdoc-superpowers/), or write TypeScript and transpile to regular JavaScript. This section will focus on the latter.
+> 💁 You can also use Preact's type definitions in plain JavaScript with [JSDoc annotations](https://fettblog.eu/typescript-jsdoc-superpowers/).
 
 ---
 
 <div><toc></toc></div>
 
 ---
 
-## TypeScript configuration
+## Configuration
 
 TypeScript includes a full-fledged JSX compiler that you can use instead of Babel. Add the following configuration to your `tsconfig.json` to transpile JSX to Preact-compatible JavaScript:
 
@@ -30,6 +30,7 @@ TypeScript includes a full-fledged JSX compiler that you can use instead of Babe
   }
 }
 ```
+
 ```json
 // TypeScript >= 4.1.1
 {
@@ -56,86 +57,147 @@ If you use TypeScript within a Babel toolchain, set `jsx` to `preserve` and let
 
 Rename your `.jsx` files to `.tsx` for TypeScript to correctly parse your JSX.
 
-## Typing components
+## Type Definitions
+
+Preact's packages (preact, preact/compat, hooks, etc.) provide TypeScript type definitions. These type definitions are explained at below.
 
-There are different ways to type components in Preact. Class components have generic type variables to ensure type safety. TypeScript sees a function as functional component as long as it returns JSX. There are multiple solutions to define props for functional components.
+## Functional Components
 
-### Function components
+The type corresponding to functional components is `FunctionComponent` type. This is type definition of `FunctionComponent` type:
 
-Typing regular function components is as easy as adding type information to the function arguments.
+```ts
+interface FunctionComponent<P = {}> {
+  (props: RenderableProps<P>, context?: any): VNode<any> | null;
+  displayName?: string;
+  defaultProps?: Partial<P>;
+}
+```
+
+> 💁 FunctionalComponent type is alias of FunctionComponent type.
+
+You can implement a functional component in TypeScript, as below.
 
 ```tsx
-type MyComponentProps = {
+import { h, FunctionComponent } from 'preact';
+
+type Props = {
   name: string;
   age: number;
 };
 
-function MyComponent({ name, age }: MyComponentProps) {
+const MyComponent: FunctionComponent<Props> = function ({ name, age }) {
   return (
     <div>
-      My name is {name}, I am {age.toString()} years old.
+      My name is {name}, I am {age} years old.
     </div>
   );
 }
 ```
 
-You can set default props by setting a default value in the function signature.
-
-```tsx
-type GreetingProps = {
-  name?: string; // name is optional!
-}
-
-function Greeting({ name = "User" }: GreetingProps) {
-  // name is at least "User"
-  return <div>Hello {name}!</div>
-}
-```
-
-Preact also ships a `FunctionComponent` type to annotate anonymous functions. `FunctionComponent` also adds a type for `children`:
+`children` is `ComponentChildren` type. `children?` as `ComponentChildren` type is added to `FunctionComponent`'s `props` by `RenderableProps` type:
 
-```tsx
-import { h, FunctionComponent } from "preact";
-
-const Card: FunctionComponent<{ title: string }> = ({ title, children }) => {
-  return (
-    <div class="card">
-      <h1>{title}</h1>
-      {children}
-    </div>
-  );
-};
+```ts
+type RenderableProps<P, RefType = any> = P & Readonly<Attributes & { children?: ComponentChildren; ref?: Ref<RefType> }>;
 ```
 
-`children` is of type `ComponentChildren`. You can specify children on your own using this type:
-
+When `children` is required, it need to be specified:
 
 ```tsx
-import { h, ComponentChildren } from "preact";
+import { h, FunctionComponent } from 'preact';
 
-type ChildrenProps = {
+type Props = {
   title: string;
   children: ComponentChildren;
 }
 
-function Card({ title, children }: ChildrenProps) {
+const Card: FunctionComponent<Props> = function ({ title, children }) {
   return (
-    <div class="card">
+    <div>
       <h1>{title}</h1>
       {children}
     </div>
   );
 };
 ```
 
-### Class components
+## Class Components
+
+Preact's `Component` class is a [generic class](https://www.typescriptlang.org/docs/handbook/generics.html#generic-classes). This type has two generic type parameters which correspond `props` and `state`. These generic type parameters are empty objects by default. `children?` as `ComponentChildren` type is added to `Component`'s `props` by `RenderableProps` type:
+
+```ts
+interface Component<P = {}, S = {}> {
+  componentWillMount?(): void;
+  componentDidMount?(): void;
+  componentWillUnmount?(): void;
+  getChildContext?(): object;
+  componentWillReceiveProps?(nextProps: Readonly<P>, nextContext: any): void;
+  shouldComponentUpdate?(
+    nextProps: Readonly<P>,
+    nextState: Readonly<S>,
+    nextContext: any
+  ): boolean;
+  componentWillUpdate?(
+    nextProps: Readonly<P>,
+    nextState: Readonly<S>,
+    nextContext: any
+  ): void;
+  getSnapshotBeforeUpdate?(oldProps: Readonly<P>, oldState: Readonly<S>): any;
+  componentDidUpdate?(
+    previousProps: Readonly<P>,
+    previousState: Readonly<S>,
+    snapshot: any
+  ): void;
+  componentDidCatch?(error: any, errorInfo: any): void;
+}
+
+abstract class Component<P, S> {
+  constructor(props?: P, context?: any);
+
+  static displayName?: string;
+  static defaultProps?: any;
+  static contextType?: Context<any>;
+
+  static getDerivedStateFromProps?(
+    props: Readonly<object>,
+    state: Readonly<object>
+  ): object | null;
+  static getDerivedStateFromError?(error: any): object | null;
+
+  state: Readonly<S>;
+  props: RenderableProps<P>;
+  context: any;
+  base?: Element | Text;
+
+  setState<K extends keyof S>(
+    state:
+      | ((
+          prevState: Readonly<S>,
+          props: Readonly<P>
+        ) => Pick<S, K> | Partial<S> | null)
+      | (Pick<S, K> | Partial<S> | null),
+    callback?: () => void
+  ): void;
+
+  forceUpdate(callback?: () => void): void;
+
+  abstract render(
+    props?: RenderableProps<P>,
+    state?: Readonly<S>,
+    context?: any
+  ): ComponentChild;
+}
+```
 
-Preact's `Component` class is typed as a generic with two generic type variables: Props and State. Both types default to the empty object, and you can specify them according to your needs.
+You can implement a class component:
 
 ```tsx
+import { h, Component } from 'preact';
+
 // Types for props
+// children is required.
 type ExpandableProps = {
   title: string;
+  children: ComponentChildren;
 };
 
 // Types for state
@@ -144,25 +206,22 @@ type ExpandableState = {
 };
 
 
-// Bind generics to ExpandableProps and ExpandableState
+// ExpandableProps and ExpandableState are passed as generic type parameter.
 class Expandable extends Component<ExpandableProps, ExpandableState> {
   constructor(props: ExpandableProps) {
     super(props);
-    // this.state is an object with a boolean field `toggle`
-    // due to ExpandableState
+    // `this.state` is a object with `toggle` property which is boolean type by ExpandableState.
     this.state = {
       toggled: false
     };
   }
-  // `this.props.title` is string due to ExpandableProps
   render() {
     return (
-      <div class="expandable">
+      <div>
         <h2>
+          // `this.props.title` is string type by ExpandableProps.
           {this.props.title}{" "}
-          <button
-            onClick={() => this.setState({ toggled: !this.state.toggled })}
-          >
+          <button onClick={() => this.setState({ toggled: !this.state.toggled })}>
             Toggle
           </button>
         </h2>
@@ -173,18 +232,17 @@ class Expandable extends Component<ExpandableProps, ExpandableState> {
 }
 ```
 
-Class components include children by default, typed as `ComponentChildren`.
+## Events
 
-## Typing events
-
-Preact emits regular DOM events. As long as your TypeScript project includes the `dom` library (set it in `tsconfig.json`), you have access to all event types that are available in your current configuration.
+Preact uses standard DOM events. Include `"DOM"` in TypeScript's [lib](https://www.typescriptlang.org/tsconfig#lib) compiler option to enable standard DOM event types.
 
 ```tsx
+import { h, Component } from 'preact';
+
 export class Button extends Component {
   handleClick(event: MouseEvent) {
-    event.preventDefault();
     if (event.target instanceof HTMLElement) {
-      alert(event.target.tagName); // Alerts BUTTON
+      console.log(event.target.tagName); // "BUTTON"
     }
   }
 
@@ -194,52 +252,67 @@ export class Button extends Component {
 }
 ```
 
-You can restrict event handlers by adding a type annotation for `this` to the function signature as the first argument. This argument will be erased after transpilation.
+You can provide a more specific type than `EventTarget` by using [this parameters](https://www.typescriptlang.org/docs/handbook/functions.html#this-parameters):
 
 ```tsx
+import { h, Component } from 'preact';
+
 export class Button extends Component {
-  // Adding the this argument restricts binding
+  // Define `this parameters`
   handleClick(this: HTMLButtonElement, event: MouseEvent) {
-    event.preventDefault();
-    if (event.target instanceof HTMLElement) {
-      console.log(event.target.localName); // "button"
-    }
+    console.log(this.tagName); // "BUTTON"
   }
 
   render() {
-    return (
-      <button onClick={this.handleClick}>{this.props.children}</button>
-    );
+    return <button onClick={this.handleClick}>{this.props.children}</button>;
   }
 }
 ```
 
-## Typing references
+You can provide a more specific type than `EventTarget` by using `TargetedEvent`. `TargetedEvent` type has two generic type parameters which corresponds `currentTarget`'s type and Event type:
 
-The `createRef` function is also generic, and lets you bind references to element types. In this example, we ensure that the reference can only be bound to `HTMLAnchorElement`. Using `ref` with any other element lets TypeScript thrown an error:
+```tsx
+import { h, Component, JSX } from 'preact';
+
+export class Button extends Component {
+  handleClick({ currentTarget }: JSX.TargetedEvent<HTMLButtonElement, Event> {
+    console.log(currentTarget.tagName); // "BUTTON"
+  }
+
+  render() {
+    return <button onClick={this.handleClick}>{this.props.children}</button>;
+  }
+}
+```
+
+## References
+
+`createRef()`is [generic type](https://www.typescriptlang.org/docs/handbook/generics.html#generic-types). You can specify a reference type by passing it as `createRef()`'s generic type parameter:
+
+```ts
+function createRef<T = any>(): RefObject<T>;
+type RefObject<T> = { current: T | null };
+```
+
+The following code is usage:
 
 ```tsx
 import { h, Component, createRef } from "preact";
 
-class Foo extends Component {
-  ref = createRef<HTMLAnchorElement>();
+export class Button extends Component {
+  ref = createRef<HTMLButtonElement>();
 
   componentDidMount() {
-    // current is of type HTMLAnchorElement
-    console.log(this.ref.current);
+    console.log(this.ref.current.tagName); // "BUTTON"
   }
 
   render() {
-    return <div ref={this.ref}>Foo</div>;
-    //          ~~~
-    //       💥 Error! Ref only can be used for HTMLAnchorElement
+    return <button ref={this.ref}>{this.props.children}</button>;
   }
 }
 ```
 
-This helps a lot if you want to make sure that the elements you `ref` to are input elements that can be e.g. focussed.
-
-## Typing context
+## Context
 
 `createContext` tries to infer as much as possible from the intial values you pass to:
 
@@ -323,7 +396,7 @@ function App() {
 
 All values become optional, so you have to do null checks when using them.
 
-## Typing hooks
+## Hooks
 
 Most hooks don't need any special typing information, but can infer types from usage.
 
@@ -350,7 +423,7 @@ const Counter = ({ initial = 0 }) => {
 
 `useEffect` does extra checks so you only return cleanup functions.
 
-```typescript
+```ts
 useEffect(() => {
   const handler = () => {
     document.title = window.innerWidth.toString();
@@ -412,7 +485,7 @@ function TextInputWithFocusButton() {
 
 For the `useReducer` hook, TypeScript tries to infer as many types as possible from the reducer function. See for example a reducer for a counter.
 
-```typescript
+```ts
 // The state type for the reducer function
 type StateType = {
   count: number;