feat(form): support Angular's signal forms with new si-form-field

spike-rabbit · spike-rabbit · commit f1312ba2c355 · 2026-07-07T10:30:53.000+02:00
Introduces a new component called `si-form-field` which is built around
Angular's signal forms.
This initial version only supports native browser inputs.
Currently missing:
- integration of the error resolution mechanism
- label in a separate column
- fieldset combination with fieldset
- documentation
diff --git a/api-goldens/element-ng/form/index.api.md b/api-goldens/element-ng/form/index.api.md
@@ -9,6 +9,7 @@ import { AfterContentChecked } from '@angular/core';
 import { AfterContentInit } from '@angular/core';
 import * as _angular_core from '@angular/core';
 import * as _angular_forms from '@angular/forms';
+import * as _angular_forms_signals from '@angular/forms/signals';
 import { DoCheck } from '@angular/core';
 import { ElementRef } from '@angular/core';
 import { FormGroup } from '@angular/forms';
@@ -21,12 +22,16 @@ import { OnInit } from '@angular/core';
 import { Provider } from '@angular/core';
 import { RequiredValidator } from '@angular/forms';
 import { Signal } from '@angular/core';
+import { SignalFormsConfig } from '@angular/forms/signals';
 import { SimpleChanges } from '@angular/core';
 import { TranslatableString } from '@siemens/element-translate-ng/translate';
 
 // @public
 export const provideFormValidationErrorMapper: (mapper: SiFormValidationErrorMapper) => Provider;
 
+// @public
+export const provideSiFormFieldConfig: (config?: SignalFormsConfig) => Provider[];
+
 // @public
 export const SI_FORM_ITEM_CONTROL: InjectionToken<SiFormItemControl>;
 
@@ -47,6 +52,12 @@ export class SiFormContainerComponent<TControl extends {
     get validFormContainerMessage(): boolean;
 }
 
+// @public
+export class SiFormFieldComponent {
+    constructor();
+    readonly label: _angular_core.InputSignal<TranslatableString>;
+}
+
 // @public (undocumented)
 export class SiFormFieldsetComponent implements DoCheck {
     readonly inline: _angular_core.InputSignalWithTransform<boolean, unknown>;
diff --git a/playwright/e2e/element-examples/si-signal-form.spec.ts b/playwright/e2e/element-examples/si-signal-form.spec.ts
@@ -0,0 +1,40 @@
+/**
+ * Copyright (c) Siemens 2016 - 2026
+ * SPDX-License-Identifier: MIT
+ */
+import { expect, test } from '../../support/test-helpers';
+
+test.describe('si-signal-form', () => {
+  const example = 'si-signal-form/si-signal-form';
+
+  test(example, async ({ page, si }) => {
+    await si.visitExample(example, false);
+    await si.runVisualAndA11yTests(undefined);
+
+    // fill the name with an invalid value
+    const name = page.getByLabel('Name', { exact: true });
+    await name.fill('a');
+
+    await page.getByText('Save').click();
+
+    await si.runVisualAndA11yTests('validated');
+
+    // verify that the angular provided error messages are linked to the controls
+    await expect(await si.getDescription(name)).toHaveText(
+      'Minimum 3 characters  Name must start with an uppercase letter'
+    );
+    await expect(await si.getDescription(page.getByLabel('Day of birth'))).toHaveText(
+      'Day of birth required'
+    );
+    await expect(await si.getDescription(page.getByLabel('Fellow passengers'))).toHaveText(
+      'Minimum 2'
+    );
+    await expect(
+      await si.getDescription(page.getByLabel('I confirm that I accept all and everything'))
+    ).toHaveText('Accept terms before joining');
+
+    // fixing the name clears its errors
+    await name.fill('Alice');
+    await expect(await si.getDescription(name)).toHaveText('');
+  });
+});
diff --git a/playwright/snapshots/si-signal-form.spec.ts-snapshots/si-signal-form--si-signal-form--validated-element-examples-chromium-dark-linux.png b/playwright/snapshots/si-signal-form.spec.ts-snapshots/si-signal-form--si-signal-form--validated-element-examples-chromium-dark-linux.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:75d6a34801b74d3eece05e97f67d64fe8111ef59fe64e36c19428a2d89534cc5
+size 35474
diff --git a/playwright/snapshots/si-signal-form.spec.ts-snapshots/si-signal-form--si-signal-form--validated-element-examples-chromium-light-linux.png b/playwright/snapshots/si-signal-form.spec.ts-snapshots/si-signal-form--si-signal-form--validated-element-examples-chromium-light-linux.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:bfa55617544c6df01fe77ab2285d57464f77ed3b97e23cc5cbe6f60f574ac72e
+size 34941
diff --git a/playwright/snapshots/si-signal-form.spec.ts-snapshots/si-signal-form--si-signal-form--validated.yaml b/playwright/snapshots/si-signal-form.spec.ts-snapshots/si-signal-form--si-signal-form--validated.yaml
@@ -0,0 +1,36 @@
+- heading "Signal form" [level=2]
+- text: Name*
+- textbox "Name*" [invalid]
+- text: Minimum 3 characters Name must start with an uppercase letter Description
+- textbox "Description"
+- text: Day of birth*
+- textbox "Day of birth*" [invalid]
+- text: Day of birth required Arrival
+- textbox "Arrival"
+- text: Departure
+- textbox "Departure"
+- text: Class of service
+- combobox "Class of service":
+  - option "First class" [selected]
+  - option "Business"
+  - option "Economy"
+- text: Fellow passengers
+- spinbutton "Fellow passengers" [invalid]: "0"
+- text: Minimum 2
+- checkbox "I confirm that I accept all and everything*" [invalid]
+- text: I confirm that I accept all and everything* Accept terms before joining
+- checkbox "I confirm that I do not care about my privacy"
+- text: I confirm that I do not care about my privacy
+- button "Cancel"
+- button "Save"
+- heading "Debugging" [level=2]
+- paragraph: "Validation status: INVALID"
+- table:
+  - rowgroup:
+    - row "Model Submitted":
+      - columnheader "Model"
+      - columnheader "Submitted"
+  - rowgroup:
+    - 'row "{ \"name\": \"a\", \"description\": \"\", \"birthday\": \"\", \"arrival\": \"\", \"departure\": \"\", \"serviceClass\": \"first\", \"fellowPassengers\": 0, \"termsAccepted\": false, \"privacyDeclined\": false } undefined"':
+      - 'cell "{ \"name\": \"a\", \"description\": \"\", \"birthday\": \"\", \"arrival\": \"\", \"departure\": \"\", \"serviceClass\": \"first\", \"fellowPassengers\": 0, \"termsAccepted\": false, \"privacyDeclined\": false }"'
+      - cell "undefined"
diff --git a/playwright/snapshots/si-signal-form.spec.ts-snapshots/si-signal-form--si-signal-form-element-examples-chromium-dark-linux.png b/playwright/snapshots/si-signal-form.spec.ts-snapshots/si-signal-form--si-signal-form-element-examples-chromium-dark-linux.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:27ce183cbb3f939a3f6e373a88fe69b40181ed0b65811796cde4338291c7223f
+size 26198
diff --git a/playwright/snapshots/si-signal-form.spec.ts-snapshots/si-signal-form--si-signal-form-element-examples-chromium-light-linux.png b/playwright/snapshots/si-signal-form.spec.ts-snapshots/si-signal-form--si-signal-form-element-examples-chromium-light-linux.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:fd2ebd4b8e99d720dfb2ebd954ee96ddbedea2d3f38b842e99c724724eeefdfd
+size 25525
diff --git a/playwright/snapshots/si-signal-form.spec.ts-snapshots/si-signal-form--si-signal-form.yaml b/playwright/snapshots/si-signal-form.spec.ts-snapshots/si-signal-form--si-signal-form.yaml
@@ -0,0 +1,35 @@
+- heading "Signal form" [level=2]
+- text: Name*
+- textbox "Name*"
+- text: Description
+- textbox "Description"
+- text: Day of birth*
+- textbox "Day of birth*"
+- text: Arrival
+- textbox "Arrival"
+- text: Departure
+- textbox "Departure"
+- text: Class of service
+- combobox "Class of service":
+  - option "First class" [selected]
+  - option "Business"
+  - option "Economy"
+- text: Fellow passengers
+- spinbutton "Fellow passengers": "0"
+- checkbox "I confirm that I accept all and everything*"
+- text: I confirm that I accept all and everything*
+- checkbox "I confirm that I do not care about my privacy"
+- text: I confirm that I do not care about my privacy
+- button "Cancel"
+- button "Save"
+- heading "Debugging" [level=2]
+- paragraph: "Validation status: INVALID"
+- table:
+  - rowgroup:
+    - row "Model Submitted":
+      - columnheader "Model"
+      - columnheader "Submitted"
+  - rowgroup:
+    - 'row "{ \"name\": \"\", \"description\": \"\", \"birthday\": \"\", \"arrival\": \"\", \"departure\": \"\", \"serviceClass\": \"first\", \"fellowPassengers\": 0, \"termsAccepted\": false, \"privacyDeclined\": false } undefined"':
+      - 'cell "{ \"name\": \"\", \"description\": \"\", \"birthday\": \"\", \"arrival\": \"\", \"departure\": \"\", \"serviceClass\": \"first\", \"fellowPassengers\": 0, \"termsAccepted\": false, \"privacyDeclined\": false }"'
+      - cell "undefined"
diff --git a/projects/element-ng/form/index.ts b/projects/element-ng/form/index.ts
@@ -3,6 +3,8 @@
  * SPDX-License-Identifier: MIT
  */
 export * from './si-form-container/si-form-container.component';
+export * from './si-form-field/si-form-field.component';
+export * from './si-form-field/si-form-field.provider';
 export * from './si-form-item/si-form-item.component';
 export * from './si-form-validation-tooltip/si-form-validation-tooltip.directive';
 export * from './form-fieldset/si-form-fieldset.component';
diff --git a/projects/element-ng/form/si-form-field/si-form-field.component.html b/projects/element-ng/form/si-form-field/si-form-field.component.html
@@ -0,0 +1,30 @@
+@if (!isFormCheck()) {
+  <ng-container [ngTemplateOutlet]="labelTemplate" />
+}
+<div class="form-item-content">
+  <ng-content />
+  @if (isFormCheck()) {
+    <ng-container [ngTemplateOutlet]="labelTemplate" />
+  }
+  <ng-container [ngTemplateOutlet]="feedbackTemplate" />
+</div>
+
+<ng-template #labelTemplate>
+  <label
+    [for]="controlId()"
+    [class.form-label]="!isFormCheck()"
+    [class.form-check-label]="isFormCheck()"
+    [class.required]="required()"
+    >{{ label() | translate }}</label
+  >
+</ng-template>
+
+<ng-template #feedbackTemplate>
+  <div class="invalid-feedback" [class.d-block]="errors().length" [attr.id]="errormessageId()">
+    @for (error of errors(); track $index) {
+      <div>
+        {{ error.message | translate }}
+      </div>
+    }
+  </div>
+</ng-template>
diff --git a/projects/element-ng/form/si-form-field/si-form-field.component.scss b/projects/element-ng/form/si-form-field/si-form-field.component.scss
@@ -0,0 +1,23 @@
+@use 'sass:map';
+@use '@siemens/element-theme/src/styles/all-variables';
+
+:host {
+  margin-block-end: map.get(all-variables.$spacers, 5);
+}
+
+:host(:not(.form-check)) {
+  display: flex;
+  flex-direction: column;
+
+  .form-item-content {
+    flex-grow: 1;
+  }
+}
+
+.form-label:empty {
+  display: none;
+}
+
+:host(.form-check:not(.form-check-inline)) {
+  display: block;
+}
diff --git a/projects/element-ng/form/si-form-field/si-form-field.component.spec.ts b/projects/element-ng/form/si-form-field/si-form-field.component.spec.ts
@@ -0,0 +1,104 @@
+/**
+ * Copyright (c) Siemens 2016 - 2026
+ * SPDX-License-Identifier: MIT
+ */
+import { Component, signal } from '@angular/core';
+import { ComponentFixture, TestBed } from '@angular/core/testing';
+import { form, FormField, minLength, required } from '@angular/forms/signals';
+import { TranslatableString } from '@siemens/element-translate-ng/translate';
+import { page } from 'vitest/browser';
+
+import { SiFormFieldComponent } from './si-form-field.component';
+
+interface Model {
+  name: string;
+  birthday: string;
+  terms: boolean;
+}
+
+@Component({
+  imports: [SiFormFieldComponent, FormField],
+  template: `
+    <si-form-field [label]="label()">
+      <input type="text" class="form-control" [formField]="form.name" />
+    </si-form-field>
+    <si-form-field label="Day of birth">
+      <input type="date" class="form-control" [formField]="form.birthday" />
+    </si-form-field>
+    <si-form-field label="Terms">
+      <input type="checkbox" class="form-check-input" [formField]="form.terms" />
+    </si-form-field>
+  `
+})
+class TestHostComponent {
+  readonly label = signal<TranslatableString>('Name');
+  readonly model = signal<Model>({ name: '', birthday: '', terms: false });
+  readonly form = form(this.model, path => {
+    required(path.name, { message: 'Name is required' });
+    minLength(path.name, 3, { message: 'Min. 3 characters' });
+    required(path.birthday, { message: 'A day of birth is required' });
+    required(path.terms, { message: 'You must accept the terms' });
+  });
+}
+
+describe('SiFormFieldComponent', () => {
+  let component: TestHostComponent;
+  let fixture: ComponentFixture<TestHostComponent>;
+
+  const nameField = page.getByRole('textbox', { name: 'Name' });
+  const birthdayField = page.getByLabelText('Day of birth');
+  const termsField = page.getByRole('checkbox', { name: 'Terms' });
+
+  const blur = async (element: Element): Promise<void> => {
+    (element as HTMLElement).focus();
+    (element as HTMLElement).blur();
+    await fixture.whenStable();
+  };
+
+  beforeEach(async () => {
+    fixture = TestBed.createComponent(TestHostComponent);
+    component = fixture.componentInstance;
+    await fixture.whenStable();
+  });
+
+  it('should mark required controls as required', async () => {
+    await expect.element(nameField).toBeRequired();
+    await expect.element(termsField).toBeRequired();
+  });
+
+  it('should not mark as invalid if the field is untouched', async () => {
+    await expect.element(nameField).not.toHaveAccessibleDescription();
+    await expect.element(nameField).not.toHaveAttribute('aria-invalid');
+  });
+
+  it('should mark the control as invalid once touched and failing validation', async () => {
+    await blur(nameField.element());
+
+    await expect.element(nameField).toHaveAttribute('aria-invalid', 'true');
+    await expect.element(nameField).toHaveAccessibleDescription(/Name is required/);
+  });
+
+  it('should clear the invalid marker once the value becomes valid', async () => {
+    await nameField.fill('Valid name');
+    await blur(nameField.element());
+
+    await expect.element(nameField).not.toHaveAttribute('aria-invalid');
+  });
+
+  it('should clear the error description once the value becomes valid', async () => {
+    await nameField.fill('Valid name');
+    await blur(nameField.element());
+
+    await expect.element(nameField).not.toHaveAccessibleDescription();
+    await expect.element(nameField).not.toHaveAttribute('aria-invalid');
+  });
+
+  it('should expose errors on all fields once the root form is marked as touched', async () => {
+    component.form().markAsTouched();
+    await fixture.whenStable();
+
+    await expect.element(nameField).toHaveAccessibleDescription(/Name is required/);
+    await expect.element(birthdayField).toHaveAccessibleDescription(/A day of birth is required/);
+    await expect.element(termsField).toHaveAccessibleDescription(/You must accept the terms/);
+  });
+});
diff --git a/projects/element-ng/form/si-form-field/si-form-field.component.ts b/projects/element-ng/form/si-form-field/si-form-field.component.ts
diff --git a/projects/element-ng/form/si-form-field/si-form-field.provider.ts b/projects/element-ng/form/si-form-field/si-form-field.provider.ts
diff --git a/src/app/examples/si-signal-form/si-signal-form.html b/src/app/examples/si-signal-form/si-signal-form.html
diff --git a/src/app/examples/si-signal-form/si-signal-form.ts b/src/app/examples/si-signal-form/si-signal-form.ts
