# Form


## Examples

### Default

```html
<m-form sr-label=${args.srLabel || ""}>
      <m-input-text name="name" label="Name" required></m-input-text>
      <m-input-text name="email" label="Email" type="email" required></m-input-text>
      <m-button type="submit">Submit</m-button>
    </m-form>
```

### DefaultForm

```html
<m-form id="example-form">
        <m-textarea name="comments" label="Comments" fullWidth></m-textarea>
        <m-input-text name="email" label="Email" required fullWidth></m-input-text>
        <m-select name="language" label="Preferred Language" placeholder="Select language" fullWidth>
          <option value="en">English</option>
          <option value="fi">Finnish</option>
          <option value="sv">Swedish</option>
          <option value="no">Norwegian</option>
          <option value="da">Danish</option>
        </m-select>
        <m-checkbox name="terms" label="I agree to the terms" required></m-checkbox>
        <div slot="buttons">
          <m-button id="my-submit-button" type="submit" variant="primary">Submit</m-button>
          <m-button id="my-reset-button" type="reset">Reset</m-button>
        </div>
      </m-form>

      <script>
        const submitButton = document.getElementById("my-submit-button");
        const resetButton = document.getElementById("my-reset-button");
        const form = document.getElementById("example-form");

        submitButton?.addEventListener("click", () => {
          form?.handleSubmit();
        });

        resetButton?.addEventListener("click", () => {
          form?.handleReset();
        });

        form?.addEventListener("form-submit", (e) => {
          console.log("Form Submitted:", e.detail);
        });

        form?.addEventListener("form-valid", (e) => {
          console.log("Form Valid:", e.detail);
        });

        form?.addEventListener("form-error", () => {
          console.log("Form has validation errors.");
        });
      </script>
```

### CustomInputs

```html
<m-form id="custom-inputs-form">
        <m-textarea name="feedback" label="Your Feedback" required fullWidth></m-textarea>
        <m-select name="language" label="Preferred Language" placeholder="Select language">
          <option value="en">English</option>
          <option value="fi">Finnish</option>
          <option value="sv">Swedish</option>
          <option value="no">Norwegian</option>
          <option value="da">Danish</option>
        </m-select>
        <m-checkbox name="subscribe" label="Subscribe to newsletter"></m-checkbox>
        <div slot="buttons">
          <m-button id="custom-submit-button" type="submit" variant="primary">Submit</m-button>
          <m-button id="custom-reset-button" type="reset">Reset</m-button>
        </div>
      </m-form>

      <script>
        const submitButton2 = document.getElementById("custom-submit-button");
        const resetButton2 = document.getElementById("custom-reset-button");
        const form2 = document.getElementById("custom-inputs-form");

        submitButton2?.addEventListener("click", () => {
          form2?.handleSubmit();
        });

        resetButton2?.addEventListener("click", () => {
          form2?.handleReset();
        });

        form2?.addEventListener("form-submit", (e) => {
          console.log("Form Submitted:", e.detail);
        });

        form2?.addEventListener("form-valid", (e) => {
          console.log("Form Valid:", e.detail);
        });

        form2?.addEventListener("form-error", () => {
          console.log("Form has validation errors.");
        });
      </script>
```

### FormWithReadonlySelect

```html
<m-form id="readonly-form">
        <m-select
          name="language"
          label="Preferred Language"
          readonly
          value="en"
          fullWidth
        >
          <option value="en">English</option>
          <option value="fi">Finnish</option>
          <option value="sv">Swedish</option>
          <option value="no">Norwegian</option>
          <option value="da">Danish</option>
        </m-select>
        <m-input-text
          name="name"
          label="Your Name"
          fullWidth
        ></m-input-text>
        <div slot="buttons">
          <m-button id="readonly-submit-button" type="submit" variant="primary">Submit</m-button>
        </div>
      </m-form>

      <div id="form-output" style="margin-top: 20px; padding: 10px; background: #f5f5f5;">
        Form submission data will appear here
      </div>

      <script>
        const readonlyForm = document.getElementById("readonly-form");
        const readonlySubmitButton = document.getElementById("readonly-submit-button");
        const output = document.getElementById("form-output");

        readonlySubmitButton?.addEventListener("click", () => {
          readonlyForm?.handleSubmit();
        });

        readonlyForm?.addEventListener("form-submit", (e) => {
          console.log("Form Submitted:", e.detail);
          if (output) {
            output.innerHTML = '<strong>Submitted Data:</strong><br>' +
              JSON.stringify(e.detail, null, 2)
                .replace(/[{}"]/g, '')
                .replace(/,/g, '<br>')
                .replace(/:/g, ': ');
          }
        });
      </script>
```

## Usage

**Use the Form component to:**

- Collect and validate user input – Ensure users can input, edit, and submit structured data, such as employee records, payroll details, or performance review feedback.
- Group related input fields – Provide a logical grouping of inputs for better readability and user experience.
- Handle form state and validation efficiently – Manage required fields, validation messages, and error handling without unnecessary complexity.

**Do not use the Form component to:**

- Replace simple input interactions – If a single input field suffices (e.g., a search bar), using a full form component may be unnecessary.
- Create a layout structure – Forms should be used for data collection, not as a general layout or section wrapper.
- Submit data automatically on input change – Forms are typically used for explicit user submissions, not automatic updates without user confirmation.
- Implement non-interactive elements – Avoid using a form for static content like informational text or dashboards.

## Other Considerations

**Form Labels & Accessibility**

- Ensure all form inputs have properly associated <label> elements or aria-label attributes for screen reader support.
- If a label needs to be hidden for a more compact UI, hide it visually but keep it accessible to screen readers.
- Group related fields using <fieldset> and <legend> when applicable (e.g., address fields, multi-step forms).
- Provide clear and descriptive error messages, ensuring they appear close to the relevant input fields.
- Use appropriate input types (email, tel, date, etc.) to optimize accessibility and improve validation.

**Validation & Error Handling**

- Ensure errors are clearly visible and have clear instructions on how to correct mistakes.
- Forms should prevent accidental data loss by prompting users before navigating away if unsaved changes exist.
- A reset function should allow users to clear the form efficiently when needed.
- Indicate a successful form submission with confirmation messages or redirect to a relevant success page or success state.

Design Rationale
- Consistency: The form component standardizes data input across the platform, ensuring a uniform experience.
- Accessibility First: By enforcing label association and validation messages, the form supports inclusive design principles.
- Flexibility: Supports both native and custom elements, allowing adaptation to complex use cases such as multi-step forms and dynamic field updates.
- Error Prevention: Provides feedback mechanisms to guide users toward accurate data entry and reduce submission errors.