`AutoControlledComponent` docs

[bmdalex]

AutoControlledComponent docs

Problem description

It is difficult for a user to understand how to use AutoControlledComponent.

For this scenario, let's assume we want to create an auto controlled component (MyAutoControlledComponent) for the value prop and pass it to an input.

Proposed solution - add documentation for AutoControlledComponent

Here is a list of steps and issues that should be documented:

type MyProps = { ... }
type MyState = { value: VALUE_TYPE, ... }

// #1
class MyAutoControlledComponent extends
  AutoControlledComponent<MyProps, MyState> {

  // #2
  static autoControlledProps = ['value']

  // #3
  static propTypes = {
    defaultValue: PROP_TYPE, // import * as PropTypes from 'prop-types'
    value: PROP_TYPE,
  }

  // #4
  static getAutoControlledStateFromProps(
    props: MyProps,
    state: MyState,
  ): Partial<MyState> {
    return { ... }
  }

  // #5
  getInitialAutoControlledState(props: MyProps): Partial<MyState> {
      return { value: MY_DEFAULT_VALUE }
  }

  renderComponent({ ElementType }) {
    // #6
    const { value = '' } = this.state
    return <ElementType {...}><input value={value} {...} /></ElementType>
  }
}

1. a template for how to extend AutoControlledComponent class

2. the fact that we need to define a static array on the component class: static autoControlledProps = ['value']

3. the fact that we need to define static propTypes object with value and defaultValue keys

4. how to derive state from props:
   use getAutoControlledStateFromProps instead of getDerivedStateFromProps

5. how to set default value for value (when the user does not set value or defaultValue):

• use getInitialAutoControlledState class method
• note that getInitialAutoControlledState cannot be an arrow function:

class MyAutoControlledComponent extends AutoControlledComponent {

  getInitialAutoControlledState = () => { // WON'T WORK!!!
      return { value: MY_DEFAULT_VALUE }
  }

  // ...
}

6. (ONLY FOR INPUTS? WHY?) the fact that we need to use '' (empty string) as default value for this.state.value before passing it to an input, otherwise we get this React error:

Warning: A component is changing a controlled input of type range to be
uncontrolled. Input elements should not switch from controlled to uncontrolled
(or vice versa). Decide between using a controlled or uncontrolled input element
for the lifetime of the component.
More info: https://fb.me/react-controlled-components

[jurokapsiar]

We are in the process of transforming the components to functional and using hooks