[docs] Improve documentation to cover shouldForwardProp

I’ve been having issues with the following code:

const Box = styled('div')({
  background: ({ color }) => color
})
...
<Box color='red' />

The attribute color="red" gets added to the <div> in the DOM. Nothing in the documentation told me how to fix this. Some fixes on Stackoverflow or Spectrum.chat look like this:

const Box = styled(({ color, ...props }) => <div {...props} />)({
  background: ({ color }) => color
})

but this is messy, and removes the Typescript typings that Box has when doing styled('div').

I dug around in the source code of styled(), and it turns out there is a filterProps property I can use:

const Box = styled('div')({
  filterProps: ['color'],
  background: ({ color }) => color
})

This works great! Exactly what I need. However, a few problems:

1. As I mentioned, nowhere in the documentation can I find reference to this, much less how to use it.
2. Typescript doesn’t like it -

const Box = styled('div')<any, { color: string }>({
  filterProps: ['color'], // error
  background: ({ color }) => color
})
/*
Type 'string[]' is not assignable to type 'string | number | JSSFontface | JSSFontface[] | CreateCSSProperties<{ color: string; }> | ((props: { color: string; }) => JSSFontface | JSSFontface[]) | ... 755 more ... | ((props: { ...; }) => VectorEffectProperty)'.
  Type 'string[]' is not assignable to type 'JSSFontface[]'.
    Type 'string' has no properties in common with type 'JSSFontface'
*/

1. It would probably make more sense adding it to the options object as a 2nd parameter:

const Box = styled('div')<any, { color: string }>({
  background: ({ color }) => color
}, {
  filterProps: ['color']
})

Implementing this change would be very simple:

1. Move this code block above the useStyles() call, and change it to this:

if (stylesOptions.filterProps) {
  filterProps = stylesOptions.filterProps;
  delete stylesOptions.filterProps;
}

1. In the Typescript type file on this line, make this change:

-   options?: WithStylesOptions<Theme>
+   options?: WithStylesOptions<Theme> & { filterProps?: string[] }

1. Throw together some quick documentation!

Since this field isn’t documented, you could argue that moving it isn’t a breaking change, since this isn’t part of the public interface. However, it’s probably better to:

1. Update the Typescript, add the option to the options object, but also allow it to still be specified in the style block
2. Add a console.warn() deprecation message in the console when NODE_ENV !== 'production'
3. Release this as a minor version bump
4. Remove the ability to specify in the style block in the next major version bump.

• The issue is present in the latest release.
• I have searched the issues of this repository and believe that this is not a duplicate.

[mnajdova]

Should we consider this solved, now that we have https://next.material-ui.com/customization/styled/?

[oliviertassinari]

I have repurposed the issue to cover v5 (instead of v4). We can:

1. Document the shouldForwardProp option: https://next.material-ui.com/guides/styled-engine/
2. Consider transient prop with the $ prefix #25925