feat(fp): WP-16 — component a11y: description wiring + alert role

Wires text-input's aria-describedby to the form-field description div
(the BSN hint was rendered but never announced), pins desc-before-error
ordering, and switches alert to role=alert for errors vs role=status
for info/ok/warning. Composition contract enforced by story play tests
(form-field+text-input, alert per variant) run in the WP-01 CI gate.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

src/app/auth/ui/login-form/login-form.component.ts

@@ -24,7 +24,13 @@ import { ButtonComponent } from '@shared/ui/button/button.component';
         i18n-description="@@login.bsnDescription"
         description="9 cijfers (demo: vul iets in)"
       >
-        <app-text-input inputId="bsn" [(ngModel)]="bsn" name="bsn" placeholder="123456789" />
+        <app-text-input
+          inputId="bsn"
+          hasDescription
+          [(ngModel)]="bsn"
+          name="bsn"
+          placeholder="123456789"
+        />
       </app-form-field>
 
       <app-form-field i18n-label="@@login.wachtwoordLabel" label="Wachtwoord" fieldId="pw" required>

src/app/shared/ui/alert/alert.component.ts

@@ -13,7 +13,10 @@ const ICON_LABELS: Record<AlertType, string> = {
 /** Atom: alert/message banner — the CIBG Huisstijl "melding"
     (designsystem.cibg.nl/componenten/meldingen). Thin wrapper over the vendored
     `.feedback feedback-*` classes: the design system owns surface + icon; we add
-    only the icon's a11y label and a content wrapper (`.feedback` is a flex row). */
+    only the icon's a11y label and a content wrapper (`.feedback` is a flex row).
+    Errors are `role="alert"` (assertive — interrupts) since they need immediate
+    attention; other variants stay `role="status"` (polite) so success/info banners
+    don't interrupt what the user is doing. */
 @Component({
   selector: 'app-alert',
   styles: [
@@ -31,7 +34,7 @@ const ICON_LABELS: Record<AlertType, string> = {
       [class.feedback-success]="type() === 'ok'"
       [class.feedback-warning]="type() === 'warning'"
       [class.feedback-error]="type() === 'error'"
-      role="status"
+      [attr.role]="type() === 'error' ? 'alert' : 'status'"
       aria-atomic="true"
     >
       <span class="icon"

src/app/shared/ui/alert/alert.stories.ts

@@ -1,4 +1,5 @@
 import type { Meta, StoryObj } from '@storybook/angular';
+import { expect, within } from 'storybook/test';
 import { AlertComponent } from './alert.component';
 
 const meta: Meta<AlertComponent> = {
@@ -12,7 +13,28 @@ const meta: Meta<AlertComponent> = {
 export default meta;
 type Story = StoryObj<AlertComponent>;
 
-export const Info: Story = { args: { type: 'info' } };
-export const Ok: Story = { args: { type: 'ok' } };
-export const Warning: Story = { args: { type: 'warning' } };
-export const Error: Story = { args: { type: 'error' } };
+// role assertions guard the polite/assertive split (WP-16): errors interrupt, others don't.
+export const Info: Story = {
+  args: { type: 'info' },
+  play: async ({ canvasElement }) => {
+    await expect(within(canvasElement).getByRole('status')).toBeInTheDocument();
+  },
+};
+export const Ok: Story = {
+  args: { type: 'ok' },
+  play: async ({ canvasElement }) => {
+    await expect(within(canvasElement).getByRole('status')).toBeInTheDocument();
+  },
+};
+export const Warning: Story = {
+  args: { type: 'warning' },
+  play: async ({ canvasElement }) => {
+    await expect(within(canvasElement).getByRole('status')).toBeInTheDocument();
+  },
+};
+export const Error: Story = {
+  args: { type: 'error' },
+  play: async ({ canvasElement }) => {
+    await expect(within(canvasElement).getByRole('alert')).toBeInTheDocument();
+  },
+};

src/app/shared/ui/form-field/form-field.stories.ts

@@ -1,5 +1,6 @@
 import type { Meta, StoryObj } from '@storybook/angular';
 import { moduleMetadata } from '@storybook/angular';
+import { expect, within } from 'storybook/test';
 import { FormFieldComponent } from './form-field.component';
 import { TextInputComponent } from '@shared/ui/text-input/text-input.component';
 
@@ -13,7 +14,7 @@ const meta: Meta<FormFieldComponent> = {
     template: `
       <form class="form-horizontal">
         <app-form-field [label]="label" [fieldId]="fieldId" [description]="description" [error]="error" [required]="required">
-          <app-text-input [inputId]="fieldId" [invalid]="!!error" placeholder="Vul in" />
+          <app-text-input [inputId]="fieldId" [hasDescription]="!!description" [invalid]="!!error" placeholder="Vul in" />
         </app-form-field>
       </form>`,
   }),
@@ -23,6 +24,13 @@ type Story = StoryObj<FormFieldComponent>;
 
 export const Default: Story = {
   args: { label: 'BSN', fieldId: 'bsn', description: '9 cijfers', required: true },
+  // Composition contract: fieldId must equal the input's id — enforced here, not by DI
+  // (see WP-16). Catches drift in the description→aria-describedby wiring.
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole('textbox');
+    await expect(input).toHaveAttribute('aria-describedby', 'bsn-desc');
+  },
 };
 export const WithError: Story = {
   args: {
@@ -31,4 +39,23 @@ export const WithError: Story = {
     error: 'Dit veld is verplicht.',
     required: true,
   },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole('textbox');
+    await expect(input).toHaveAttribute('aria-describedby', 'street-error');
+  },
+};
+export const WithDescriptionAndError: Story = {
+  args: {
+    label: 'BSN',
+    fieldId: 'bsn',
+    description: '9 cijfers',
+    error: 'Ongeldig BSN.',
+    required: true,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole('textbox');
+    await expect(input).toHaveAttribute('aria-describedby', 'bsn-desc bsn-error');
+  },
 };

src/app/shared/ui/text-input/text-input.component.ts

@@ -1,4 +1,4 @@
-import { Component, forwardRef, input } from '@angular/core';
+import { Component, booleanAttribute, forwardRef, input } from '@angular/core';
 import { ControlValueAccessor, NG_VALUE_ACCESSOR } from '@angular/forms';
 
 /** Atom: text input. Utrecht textbox wired up as a form control (ngModel/reactive). */
@@ -22,7 +22,7 @@ import { ControlValueAccessor, NG_VALUE_ACCESSOR } from '@angular/forms';
       [type]="type()"
       [id]="inputId()"
       [attr.aria-invalid]="invalid() ? 'true' : null"
-      [attr.aria-describedby]="invalid() && inputId() ? inputId() + '-error' : null"
+      [attr.aria-describedby]="describedBy()"
       [placeholder]="placeholder()"
       [disabled]="disabled"
       [value]="value"
@@ -39,12 +39,24 @@ export class TextInputComponent implements ControlValueAccessor {
   placeholder = input('');
   invalid = input(false);
   inputId = input<string>();
+  /** Set when the paired form-field renders a `-desc` hint, so it gets announced. */
+  hasDescription = input(false, { transform: booleanAttribute });
 
   value = '';
   disabled = false;
   onChange: (v: string) => void = () => {};
   onTouched: () => void = () => {};
 
+  describedBy(): string | null {
+    const id = this.inputId();
+    if (!id) return null;
+    const ids = [
+      ...(this.hasDescription() ? [`${id}-desc`] : []),
+      ...(this.invalid() ? [`${id}-error`] : []),
+    ];
+    return ids.length ? ids.join(' ') : null;
+  }
+
   onInput(e: Event) {
     this.value = (e.target as HTMLInputElement).value;
     this.onChange(this.value);