docs: add people-picker form associated custom elements spec

specs/mgt-people-picker.md

@@ -46,6 +46,113 @@ The people picker components provides a way for developers to select users, grou
 <mgt-people-picker group-ids="02bd9fd6-8f93-4758-87c3-1fb73740a315,06f62f70-9827-4e6e-93ef-8e0f2d9b7b23"></mgt-people-picker>
 ```
 
+## Form validation
+
+The mgt-people-picker component can be used as a form control in a form, and the form can be submitted with the attributes as part of the form data. It makes use of the form-associated custom elements API, which provides a new set of capabilities that make custom controls work like built-in form controls. The component will implement the form-associated behaviors to participate in form submission, validation, and other form-related behaviors. [Read more](https://docs.google.com/document/d/1JO8puctCSpW-ZYGU8lF-h4FWRIDQNDVexzHoOQ2iQmY/edit?pli=1#heading=h.2hgix04sc53t) about the form-associated custom elements API and [how to create custom form controls](https://css-tricks.com/creating-custom-form-controls-with-elementinternals/).
+
+The following properties are used as part of the required field validation logic for the component.
+
+
+| Property on the object          | Description                                                                                                 | Type of property                                                                                                      |
+| ------------------ | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `required`         | Determines if the required field validation is to be executed. When `true` the field is invalid if the the selectedPeople property contains zero items.             | `boolean`                                                               |
+| `selectedPeople`  | Sets the selected people programmatically.                                                                 | `array` |                                             |
+| `disabled`         | Sets whether the people picker is disabled. When disabled, the user is not able to search or select people. | `boolean`                                                                 |
+
+## Implementing the form-associated behaviors
+
+The implementation of the form-associated custom elements will include the following:
+
+### Identify the element as a form-associated custom element
+
+The `mgt-people-picker` component is identified as a form-associated custom element by adding a static `formAssociated` property to the custom element class to tell the browser to treat the element like a form control.
+
+```javascript
+export class MgtPeoplePicker extends MgtTemplatedTaskComponent {
+    // ...
+    static formAssociated = true;
+    // ...
+}
+```
+
+### Providing access to the form control's internals
+
+The component will implement the attachInternals() method on the element to get access to extra methods and properties for form controls, like setFormValue() and setValidity(). This method returns the `ElementInternals` object that provides access to the form control APIs.
+
+It will also set the internal value of the control.
+
+```javascript
+export class MgtPeoplePicker extends MgtTemplatedTaskComponent {
+    constructor() {
+        super();
+        this._internals = this.attachInternals();
+    // ...
+    }
+}
+```
+
+### Managing the form control's value
+
+The mgt-people-picker will manage its form value through the value property. This value will be the selected people in the picker.
+
+```javascript
+export class MgtPeoplePicker extends MgtTemplatedTaskComponent {
+    // ...
+    get value() {
+        return this.selectedPeople.join(',');
+    }
+    // ...
+}
+```
+
+### Handling form control validation state
+
+The mgt-people-picker will handle validation by using the setValidity() provided by the ElementInternals object, which you get by calling attachInternals() on your custom element, to indicate whether the element is currently valid or not.
+
+```javascript
+export class MgtPeoplePicker extends MgtTemplatedTaskComponent {
+    // ...
+    checkValidity() {
+        const isValid = this.selectedPeople && this.selectedPeople.length > 0;
+        this._internals.setValidity({
+            customError: !isValid
+        }, isValid ? '' : 'At least one person must be selected.');
+
+        return isValid;
+    }
+    // ...
+}
+```
+
+### Manage Form Submission
+
+The mgt-people-picker will manage form submission by implementing the formDisabledCallback() and formResetCallback() methods.
+
+```javascript
+export class MgtPeoplePicker extends MgtTemplatedTaskComponent {
+    // ...
+    formDisabledCallback(isDisabled) {
+        this.disabled = isDisabled;
+    }
+
+    formResetCallback() {
+        this.selectedPeople = [];
+    }
+    // ...
+}
+```
+## Future Validation Enhancements
+
+In future versions of the `mgt-people-picker`, we plan to add more advanced validation features to give developers more control over the selection process and ensure that users select the correct number of people.
+
+### Range Validation
+
+We plan to add support for range validation. This will allow developers to specify a minimum and maximum number of people that can be selected. This will be useful in scenarios where there is a hard limit on the number of people that can be selected. For example, a developer could specify that at least 2 people and at most 5 people must be selected.
+
+```html
+<mgt-people-picker min-selected="2" max-selected="5"></mgt-people-picker>
+```
+
 ## Events
 
 The following events are fired from the component.