Improve documentation for boxed values in form control

I’m submitting a …

[ ] Regression (behavior that used to work and stopped working in a new release)
[ ] Bug report 
[ ] Feature request
[x] Documentation issue or request
[ ] Support request

Current behavior …

https://github.com/angular/angular/blob/acf6075ca9aa92121bb0166b2b7560aeb2c167ff/packages/forms/src/form_builder.ts#L57 and https://github.com/angular/angular/blob/acf6075ca9aa92121bb0166b2b7560aeb2c167ff/packages/forms/src/form_builder.ts#L105

The documentation about the parameter formState in the method control(..) and the parameter controlsConfig in the method group(..) (see line reference) doesn’t explain very well how to set it. Additionally, the type hints has presence of anys and makes it harder to understand.

Expected behavior

I propose the follow type hints changes to clarify the situation.

For the formState type hint: string | { value: string, disabled: boolean }

For the controlsConfig type hint: { [key: string]: [string | {value: string, disabled: boolean}, ...any[]] }

[AndrewKushnir]

Hi @jpchavat, thanks for creating this ticket.

It looks like there are 2 parts that we need to look into:

• improvements to the Forms package typings. This is one of the pain points for Forms users and we plan to perform improvements in this area, see https://github.com/angular/angular/issues/13721#issuecomment-637698836.
• additional docs on possible values for the formState argument to better describe that an object with value and disabled keys can be used. We can look into this part once the types are updated (so we can refer to updated types in additional docs).

Thank you.

[kapunahelewong]

Thank you, @treeindev! I’d like confirmation on this, too. Let’s see if @AndrewKushnir can give us some insight on this change. @AndrewKushnir, could you share your thoughts on this?