Update "Form Controls" documentation to be more explicit

[andy-blum]

Describe the bug

The current Form Controls documentation states:

Shoelace solves this problem by using the formdata event, which is available in all modern browsers. This means, when a form is submitted, Shoelace form controls will automatically append their values to the FormData object that’s used to submit the form. In most cases, things will “just work.” However, if you’re using a form serialization library, it might need to be adapted to recognize Shoelace form controls.

I have spent the last couple hours trying to figure out why my form setup wouldn't "just work" and after finding no issues opened here and stripping the issue down from my stack to a static HTML page, finally dug into the source code to see how this was designed to work.

The code that should make this "just work" is in /src/internal/form.ts

  private handleFormData = (event: FormDataEvent) => {
    const disabled = this.options.disabled(this.host);
    const name = this.options.name(this.host);
    const value = this.options.value(this.host);

    // For buttons, we only submit the value if they were the submitter. This is currently done in doAction() by
    // injecting the name/value on a temporary button, so we can just skip them here.
    const isButton = this.host.tagName.toLowerCase() === 'sl-button';

    if (!disabled && !isButton && typeof name === 'string' && name.length > 0 && typeof value !== 'undefined') {
      if (Array.isArray(value)) {
        (value as unknown[]).forEach(val => {
          event.formData.append(name, (val as string | number | boolean).toString());
        });
      } else {
        event.formData.append(name, (value as string | number | boolean).toString());
      }
    }
  };

There are several criteria that must be met for the form elements to work that are not documented on the Form Controls page:

• Element must not be disabled
• Element must not be a button
• Element must have a string-type name attribute with at least one character
• Element must have a value

The part I had been missing was the name attribute, and I see that its relationship to form data is documented in the sl-input component's "Properties" section, but it would be helpful to outline those requirements more explicitly on the Form Controls page as well

[claviska]

We try to follow the same conventions as native form controls. On one hand, reiterating everything you can find about forms on, say, MDN will lead to massive bloat in our docs. On the other, we are currently making an assumption that you already know how HTML forms work.

Thanks for the feedback. We'll consider how to update the docs in a way that strikes the right balance!