@porsche-design-system/components-angular 4.6.0-rc.0 → 4.6.0-rc.2

package/{skill → skills/pds-knowledge-angular}/references/components/p-pin-code/p-pin-code.md

@@ -58,6 +58,10 @@ In general, avoid using the `disabled="true"` state. Disabled elements are no lo
 - **Do** use the component state/message API so validation and status changes are announced.
 - **Don't** use `hide-label` without an accessible name.
 
+## Integration examples
+
+See [accessibility integration examples](./accessibility.md) for paired anti-pattern and recommended implementations.
+
 ## API
 
 ### Properties
@@ -77,14 +81,14 @@ In general, avoid using the `disabled="true"` state. Disabled elements are no lo
 | `required` | `boolean` | `false` | Marks the pin code as required so the form cannot be submitted until all fields are filled. |
 | `state` | `'none'` `'error'` `'success'` | `'none'` | Sets the validation state of the pin code, which controls its visual appearance and feedback message style (`none`, `success`, `error`). |
 | `type` | `'number'` `'password'` | `'number'` | Controls whether the individual input fields mask their content as password dots (`password`) or show digits (`number`). |
-| `value` | `string` | `''` | Sets the current concatenated value of all pin code fields and allows setting the initial value. |
+| `value` | `string | number | null` | `''` | Sets the current concatenated value. Numbers are accepted for programmatic assignment, but user input updates the value as a string. |
 
 ### Events
 
 | Event | Type | Description |
 | --- | --- | --- |
 | `blur` | `CustomEvent<void>` | Emitted when the pin code component loses focus after the user finishes entering characters. |
-| `change` | `CustomEvent<PinCodeChangeEventDetail>`<br>`{ value: string; isComplete: boolean }` | Emitted when the pin code value changes as the user types, carrying the new concatenated value in the event detail. |
+| `change` | `CustomEvent<PinCodeChangeEventDetail>`<br>`{ value: string; isComplete: boolean }` | Emitted when the pin code value changes as the user types, carrying `{ value: string; isComplete: boolean }` in the event detail. |
 
 ### Controlled properties
 

package/skills/pds-knowledge-angular/references/components/p-popover/accessibility.md

@@ -0,0 +1,61 @@
+# p-popover accessibility integration examples
+
+## Integration examples
+
+### ARIA on component host vs aria prop
+
+#### ❌ Anti-pattern
+
+```html
+<p-popover aria-label="Specification details" description="Additional specification details."></p-popover>
+```
+
+#### ✅ Recommended
+
+```html
+<p-popover [aria]="{'aria-label': 'Specification details'}" description="Additional specification details."></p-popover>
+```
+
+### Custom slotted trigger without accessible name
+
+#### ❌ Anti-pattern
+
+```html
+<p-popover>
+  <button slot="button" type="button"></button>
+  Additional specification details.
+</p-popover>
+```
+
+#### ✅ Recommended
+
+```html
+<p-popover description="Additional specification details."></p-popover>
+
+<!-- or provide an accessible name on a custom slotted button -->
+
+<p-popover>
+  <button slot="button" type="button" ariaLabel="Specification details">
+    i
+  </button>
+  Additional specification details.
+</p-popover>
+```
+
+### Custom slotted trigger without aria-expanded
+
+#### ❌ Anti-pattern
+
+```html
+<p-popover>
+  <button slot="button" type="button"></button>
+</p-popover>
+```
+
+#### ✅ Recommended
+
+```html
+<p-popover>
+  <button slot="button" type="button" ariaExpanded="false"></button>
+</p-popover>
+```

package/{skill → skills/pds-knowledge-angular}/references/components/p-popover/p-popover.md

@@ -65,6 +65,10 @@ In **controlled** mode the consumer owns the `open` state, so the slotted trigge
 - **Don't** use an unnamed custom slotted trigger button.
 - **Don't** add native `aria-*` attributes directly on the component host.
 
+## Integration examples
+
+See [accessibility integration examples](./accessibility.md) for paired anti-pattern and recommended implementations.
+
 ## API
 
 ### Properties

package/skills/pds-knowledge-angular/references/components/p-radio-group/accessibility.md

@@ -0,0 +1,63 @@
+# p-radio-group accessibility integration examples
+
+## Integration examples
+
+### Missing group label
+
+#### ❌ Anti-pattern
+
+```html
+<p-radio-group name="fuel">
+  <p-radio-group-option value="electric" label="Electric"></p-radio-group-option>
+  <p-radio-group-option value="hybrid" label="Hybrid"></p-radio-group-option>
+</p-radio-group>
+```
+
+#### ✅ Recommended
+
+```html
+<p-radio-group label="Powertrain" name="fuel" description="Select your preferred powertrain.">
+  <p-radio-group-option value="electric" label="Electric"></p-radio-group-option>
+  <p-radio-group-option value="hybrid" label="Hybrid"></p-radio-group-option>
+</p-radio-group>
+```
+
+### Hidden label without accessible name
+
+#### ❌ Anti-pattern
+
+```html
+<p-radio-group name="fuel" [hideLabel]="true">
+  <p-radio-group-option value="electric" label="Electric"></p-radio-group-option>
+  <p-radio-group-option value="hybrid" label="Hybrid"></p-radio-group-option>
+</p-radio-group>
+```
+
+#### ✅ Recommended
+
+```html
+<p-radio-group label="Powertrain" name="fuel" [hideLabel]="true">
+  <p-radio-group-option value="electric" label="Electric"></p-radio-group-option>
+  <p-radio-group-option value="hybrid" label="Hybrid"></p-radio-group-option>
+</p-radio-group>
+```
+
+### Validation feedback via state and message API
+
+#### ❌ Anti-pattern
+
+```html
+<p-radio-group label="Powertrain" name="fuel" [aria-invalid]="true" message="Required">
+  <p-radio-group-option value="electric" label="Electric"></p-radio-group-option>
+  <p-radio-group-option value="hybrid" label="Hybrid"></p-radio-group-option>
+</p-radio-group>
+```
+
+#### ✅ Recommended
+
+```html
+<p-radio-group label="Powertrain" name="fuel" [required]="true" state="error" message="Select a powertrain to continue.">
+  <p-radio-group-option value="electric" label="Electric"></p-radio-group-option>
+  <p-radio-group-option value="hybrid" label="Hybrid"></p-radio-group-option>
+</p-radio-group>
+```

package/{skill → skills/pds-knowledge-angular}/references/components/p-radio-group/examples/Form.ts

@@ -1,6 +1,6 @@
 import { ChangeDetectionStrategy, Component } from '@angular/core';
 import { FormControl, FormGroup, FormsModule, ReactiveFormsModule } from '@angular/forms';
-import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+import { PorscheDesignSystemModule, type PRadioGroupProps } from '@porsche-design-system/components-angular';
 
 @Component({
   selector: 'porsche-design-system-app',
@@ -27,7 +27,7 @@ import { PorscheDesignSystemModule } from '@porsche-design-system/components-ang
 })
 export class ExampleComponent {
   form = new FormGroup({
-    myRadioGroup: new FormControl<string>(''),
+    myRadioGroup: new FormControl<PRadioGroupProps['value']>(null),
   });
 
   submittedValue: any = undefined;

package/{skill → skills/pds-knowledge-angular}/references/components/p-radio-group/p-radio-group.md

@@ -6,7 +6,7 @@ The `p-radio-group` component is a versatile custom form element that enables th
 >
 > The `blur` event is emitted whenever the focused `p-radio-group-option` changes — not only when the entire `p-radio-group` loses focus. This means that switching between options within the same group will also trigger a `blur` event for the previously focused option.
 
-Options are slotted using the `p-radio-group-option` component. Each option needs to have an assigned value, which can be passed via an attribute or property and needs to be of type string. Initial selection states can only be achieved using the value property on the `p-radio-group` component. If an option should be visible but not selectable, it can be disabled by using the `disabled` attribute.
+Options are slotted using the `p-radio-group-option` component. Each option needs an assigned `string` or `number` value. The `p-radio-group` value matches an option strictly by type and value, so a number does not match the equivalent string. `undefined` and `null` are reserved for the radio group's unselected state and are not valid option values. Initial selection states can only be achieved using the `value` property on the `p-radio-group` component. If an option should be visible but not selectable, it can be disabled using the `disabled` attribute.
 
 A `label` is a caption which informs the user what information a particular form field is asking for. The `p-radio-group` component can be used with or without a label, but it's recommended to keep the label visible for better accessibility whenever possible. When used without a label, it's best practice to provide a descriptive label text for screen readers.
 
@@ -70,6 +70,10 @@ In general, avoid using the `disabled` state. Disabled elements are no longer fo
 - **Don't** rely on adjacent text instead of the group `label` prop.
 - **Don't** use `hide-label` without an accessible name.
 
+## Integration examples
+
+See [accessibility integration examples](./accessibility.md) for paired anti-pattern and recommended implementations.
+
 ## Tests
 
 ### Automated
@@ -105,7 +109,7 @@ In general, avoid using the `disabled` state. Disabled elements are no longer fo
 | `name` _(required)_ | `string` | `undefined` | Sets the shared name attribute for all radio buttons in the group, grouping them for mutually exclusive selection. |
 | `required` | `boolean` | `false` | Marks the radio group as required so the form cannot be submitted until one option is selected. |
 | `state` | `'none'` `'error'` `'success'` | `'none'` | Sets the validation state of the radio group, controlling its visual appearance and feedback message style (`none`, `success`, `error`). |
-| `value` | `string` | `''` | Sets the currently selected value that pre-selects the matching radio option and reflects user changes. |
+| `value` | `string | number | null` | `undefined` | Sets the currently selected value that pre-selects the matching radio option and reflects user changes. Matches an option strictly by type and value, meaning string or number only match an option whose value has the same type and equal value. Use undefined or null for no preselection; these values never match an option because every option requires a string or number value. Please note that FormData always serializes values as strings, so when participating in a native (uncontrolled) form a number value is restored as string via formStateRestoreCallback and will no longer strictly match a number-typed option. This limitation only applies to native form state restoration; in controlled forms (where the consumer manages value directly via the change event), the number type is preserved end-to-end. |
 
 ### Events
 
@@ -139,7 +143,7 @@ Allowed parent: `p-radio-group`.
 | `disabled` | `boolean` | `false` | Prevents this option from being selected and excludes its value from form submissions while it is disabled. |
 | `label` | `string` | `undefined` | Sets the visible label text displayed next to the radio button that the user reads to identify the option. |
 | `loading` _(experimental)_ | `boolean` | `false` | @experimental Disables this option and shows a spinner to indicate that this particular option is in a loading state. |
-| `value` | `string` | `undefined` | Sets the value submitted with the form data when this radio option is selected within its parent group. |
+| `value` _(required)_ | `string | number` | `undefined` | Sets the required option value. Must be a string or number and is selected when it strictly matches the parent `p-radio-group` value by type and value. |
 
 #### Slots
 

package/skills/pds-knowledge-angular/references/components/p-scroller/accessibility.md

@@ -0,0 +1,31 @@
+# p-scroller accessibility integration examples
+
+## Integration examples
+
+### ARIA on component host vs aria prop
+
+#### ❌ Anti-pattern
+
+```html
+<p-scroller aria-label="Section tags" aria-description="Section tags for the section overview">
+  <p-tag>
+    Overview
+  </p-tag>
+  <p-tag>
+    Equipment
+  </p-tag>
+</p-scroller>
+```
+
+#### ✅ Recommended
+
+```html
+<p-scroller [aria]="{'aria-label': 'Section tags', 'aria-description': 'Section tags for the section overview'}">
+  <p-tag>
+    Overview
+  </p-tag>
+  <p-tag>
+    Equipment
+  </p-tag>
+</p-scroller>
+```

package/{skill → skills/pds-knowledge-angular}/references/components/p-scroller/p-scroller.md

@@ -57,6 +57,10 @@ If the `p-scroller` component is accessed by keyboard navigation and is focused,
 - **Do** pass `aria-label` and `aria-description` via the `aria` prop, not as host attributes.
 - **Don't** add native `aria-*` attributes directly on the component host.
 
+## Integration examples
+
+See [accessibility integration examples](./accessibility.md) for paired anti-pattern and recommended implementations.
+
 ## API
 
 ### Properties

package/skills/pds-knowledge-angular/references/components/p-segmented-control/accessibility.md

@@ -0,0 +1,67 @@
+# p-segmented-control accessibility integration examples
+
+## Integration examples
+
+### Missing group label
+
+#### ❌ Anti-pattern
+
+```html
+<p-segmented-control name="size">
+  <p-segmented-control-item value="s">
+    S
+  </p-segmented-control-item>
+  <p-segmented-control-item value="m">
+    M
+  </p-segmented-control-item>
+</p-segmented-control>
+```
+
+#### ✅ Recommended
+
+```html
+<p-segmented-control label="T-shirt size" name="size" description="Select your preferred size.">
+  <p-segmented-control-item value="s">
+    S
+  </p-segmented-control-item>
+  <p-segmented-control-item value="m">
+    M
+  </p-segmented-control-item>
+</p-segmented-control>
+```
+
+### Hidden label without accessible name
+
+#### ❌ Anti-pattern
+
+```html
+<p-segmented-control name="size" [hideLabel]="true">
+  <p-segmented-control-item value="s">
+    S
+  </p-segmented-control-item>
+</p-segmented-control>
+```
+
+#### ✅ Recommended
+
+```html
+<p-segmented-control label="T-shirt size" name="size" [hideLabel]="true">
+  <p-segmented-control-item value="s">
+    S
+  </p-segmented-control-item>
+</p-segmented-control>
+```
+
+### Validation feedback via state and message API
+
+#### ❌ Anti-pattern
+
+```html
+<p-segmented-control label="T-shirt size" name="size" [aria-invalid]="true" message="Required"></p-segmented-control>
+```
+
+#### ✅ Recommended
+
+```html
+<p-segmented-control label="T-shirt size" name="size" [required]="true" state="error" message="Select a size to continue."></p-segmented-control>
+```

package/{skill → skills/pds-knowledge-angular}/references/components/p-segmented-control/examples/Form.ts

@@ -1,6 +1,6 @@
 import { ChangeDetectionStrategy, Component } from '@angular/core';
 import { FormControl, FormGroup, FormsModule, ReactiveFormsModule } from '@angular/forms';
-import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+import { PorscheDesignSystemModule, PSegmentedControlProps } from '@porsche-design-system/components-angular';
 
 @Component({
   selector: 'porsche-design-system-app',
@@ -26,7 +26,7 @@ import { PorscheDesignSystemModule } from '@porsche-design-system/components-ang
 })
 export class ExampleComponent {
   form = new FormGroup({
-    mySegmentedControl: new FormControl<string | number | undefined>({ value: undefined, disabled: false }),
+    mySegmentedControl: new FormControl<PSegmentedControlProps['value']>(null),
   });
 
   submittedValue: any = undefined;

package/{skill → skills/pds-knowledge-angular}/references/components/p-segmented-control/p-segmented-control.md

@@ -86,6 +86,10 @@ In general, avoid using the `disabled` state. Disabled elements are no longer fo
 - **Don't** add native `aria-*` attributes directly on the component host.
 - **Don't** use `hide-label` without an accessible name.
 
+## Integration examples
+
+See [accessibility integration examples](./accessibility.md) for paired anti-pattern and recommended implementations.
+
 ## API
 
 ### Properties
@@ -104,7 +108,7 @@ In general, avoid using the `disabled` state. Disabled elements are no longer fo
 | `noWrap` | `boolean` | `false` | Prevents items from wrapping to new rows and renders them in a single horizontally scrollable row instead. |
 | `required` | `boolean` | `false` | Marks the segmented control as required so the form cannot be submitted until one option is selected. |
 | `state` | `'none'` `'error'` `'success'` | `'none'` | Sets the validation state of the segmented control, controlling its visual appearance and feedback message style (`none`, `success`, `error`). |
-| `value` | `string | number` | `undefined` | Sets the currently selected item's value and pre-selects the matching option when the component renders. |
+| `value` | `string | number | null` | `undefined` | Sets the currently selected item's value and pre-selects the matching option when the component renders. Matches an item strictly by type and value, meaning string or number only match an item whose value has the same type and equal value. Use undefined or null for no preselection. Please note that FormData always serializes values as strings, so when participating in a native (uncontrolled) form a number value is restored as string via formStateRestoreCallback and will no longer strictly match a number-typed item. This limitation only applies to native form state restoration; in controlled forms (where the consumer manages value directly via the change event), the number type is preserved end-to-end. |
 
 ### Events
 
@@ -141,7 +145,7 @@ Allowed parent: `p-segmented-control`.
 | --- | --- | --- | --- |
 | `aria` | `SegmentedControlItemAriaAttribute` | `undefined` | Sets ARIA attributes on the item's button element to improve accessibility for screen readers. |
 | `disabled` | `boolean` | `false` | Prevents this item from being selected and visually dims it; the parent's value will not change to this item's value. |
-| `icon` | `''`<br>one of 290 icon names — see [icon names](references/icons.md) | `undefined` | Sets an icon rendered inside the item button using an icon name from the PDS icon library. |
+| `icon` | `''`<br>one of 293 icon names — see [icon names](references/icons.md) | `undefined` | Sets an icon rendered inside the item button using an icon name from the PDS icon library. |
 | `iconSource` | `string` | `undefined` | Sets a URL to a custom SVG icon for the item button, overriding the built-in icon set. |
 | `label` | `string` | `undefined` | Sets a visible text label rendered inside the item button, used when no slotted content is provided. |
 | `value` _(required)_ | `string | number` | `undefined` | Sets the value emitted by the parent `p-segmented-control` when this item is selected. This property is*required**. |

package/skills/pds-knowledge-angular/references/components/p-select/accessibility.md

@@ -0,0 +1,140 @@
+# p-select accessibility integration examples
+
+## Integration examples
+
+### Prompt option used instead of a label
+
+#### ❌ Anti-pattern
+
+```html
+<p-select name="model">
+  <p-select-option value="">
+    Select a model
+  </p-select-option>
+  <p-select-option value="carrera">
+    911 Carrera
+  </p-select-option>
+  <p-select-option value="carrera-s">
+    911 Carrera S
+  </p-select-option>
+</p-select>
+```
+
+#### ✅ Recommended
+
+```html
+<p-select label="Porsche model" name="model" description="Choose the model for your configuration.">
+  <p-select-option value="carrera">
+    911 Carrera
+  </p-select-option>
+  <p-select-option value="carrera-s">
+    911 Carrera S
+  </p-select-option>
+</p-select>
+```
+
+### Ambiguous option labels without field context
+
+#### ❌ Anti-pattern
+
+```html
+<p-select label="Model" name="model">
+  <p-select-option value="base">
+    Base
+  </p-select-option>
+  <p-select-option value="s">
+    S
+  </p-select-option>
+</p-select>
+```
+
+#### ✅ Recommended
+
+```html
+<p-select label="Porsche 911 trim" name="model" description="Select the trim level for your configuration.">
+  <p-select-option value="carrera">
+    911 Carrera
+  </p-select-option>
+  <p-select-option value="carrera-s">
+    911 Carrera S
+  </p-select-option>
+</p-select>
+```
+
+### Hidden label without accessible name
+
+#### ❌ Anti-pattern
+
+```html
+<p-select name="model" [hideLabel]="true">
+  <p-select-option value="carrera">
+    911 Carrera
+  </p-select-option>
+</p-select>
+```
+
+#### ✅ Recommended
+
+```html
+<p-select label="Porsche model" name="model" [hideLabel]="true">
+  <p-select-option value="carrera">
+    911 Carrera
+  </p-select-option>
+</p-select>
+```
+
+### Validation feedback via state and message API
+
+#### ❌ Anti-pattern
+
+```html
+<p-select label="Porsche model" name="model" [aria-invalid]="true" message="Required">
+  <p-select-option value="carrera">
+    911 Carrera
+  </p-select-option>
+  <p-select-option value="carrera-s">
+    911 Carrera S
+  </p-select-option>
+</p-select>
+```
+
+#### ✅ Recommended
+
+```html
+<p-select label="Porsche model" name="model" state="error" message="Select a model to continue with your configuration.">
+  <p-select-option value="carrera">
+    911 Carrera
+  </p-select-option>
+  <p-select-option value="carrera-s">
+    911 Carrera S
+  </p-select-option>
+</p-select>
+```
+
+### Error state without recovery guidance
+
+#### ❌ Anti-pattern
+
+```html
+<p-select label="Porsche model" name="model" state="error" message="Invalid">
+  <p-select-option value="carrera">
+    911 Carrera
+  </p-select-option>
+  <p-select-option value="carrera-s">
+    911 Carrera S
+  </p-select-option>
+</p-select>
+```
+
+#### ✅ Recommended
+
+```html
+<p-select label="Porsche model" name="model" [required]="true" state="error" message="Select a Porsche model. This field is required to continue.">
+  <p-select-option value="carrera">
+    911 Carrera
+  </p-select-option>
+  <p-select-option value="carrera-s">
+    911 Carrera S
+  </p-select-option>
+</p-select>
+```

package/{skill → skills/pds-knowledge-angular}/references/components/p-select/examples/AsyncFilter.ts

@@ -31,6 +31,9 @@ import {
         (change)="$event.stopPropagation()"
       ></p-input-search>
 
+      <!-- Persistent status announcer for assistive technologies (keep always in the DOM) -->
+      <div slot="options-status" class="sr-only" aria-live="polite" aria-atomic="true">{{ filterStatusMessage }}</div>
+
       <!-- Initial skeleton loading -->
       @if (initialLoading && !error) {
         @for (_ of [1,2,3,4,5,6,7,8,9]; track $index) {
@@ -45,15 +48,14 @@ import {
         </p-select-option>
       }
 
-      <!-- No filter results -->
-      @if (!initialLoading && options.length === 0 && !error) {
+      <!-- No filter results (visual only; announcements come from the live region) -->
+      @if (!initialLoading && !loading && options.length === 0 && !error) {
         <div
           slot="options-status"
           class="text-contrast-medium cursor-not-allowed py-static-sm px-[12px]"
-          role="alert"
+          aria-hidden="true"
         >
-          <span aria-hidden="true">–</span>
-          <span class="sr-only">No results found</span>
+          –
         </div>
       }
 
@@ -83,6 +85,7 @@ export class ExampleComponent {
   initialLoading = false;
   loading = false;
   error: string | null = null;
+  filterStatusMessage = '';
 
   private hasLoadedOnce = false;
   private currentFetchId = 0;
@@ -94,6 +97,7 @@ export class ExampleComponent {
     const fetchId = ++this.currentFetchId;
     if (isInitial) this.initialLoading = true;
     else this.loading = true;
+    this.updateFilterStatusMessage();
 
     this.cdr.markForCheck();
 
@@ -122,6 +126,7 @@ export class ExampleComponent {
     } finally {
       if (isInitial) this.initialLoading = false;
       else this.loading = false;
+      this.updateFilterStatusMessage();
 
       this.cdr.markForCheck();
     }
@@ -146,4 +151,26 @@ export class ExampleComponent {
       this.fetchOptions(undefined, true);
     }
   }
+
+  private updateFilterStatusMessage(): void {
+    if (this.error) {
+      this.filterStatusMessage = '';
+      return;
+    }
+    if (this.initialLoading || this.loading) {
+      this.filterStatusMessage = 'Loading options';
+      return;
+    }
+    const term = this.searchValue.trim();
+    if (!term) {
+      this.filterStatusMessage = '';
+      return;
+    }
+    if (this.options.length === 0) {
+      this.filterStatusMessage = 'No results found';
+      return;
+    }
+    this.filterStatusMessage =
+      this.options.length === 1 ? '1 result available' : `${this.options.length} results available`;
+  }
 }

package/{skill → skills/pds-knowledge-angular}/references/components/p-select/p-select.md

@@ -79,6 +79,10 @@ In general, avoid using the `disabled` state. Disabled elements are no longer fo
 - **Don't** use very short or ambiguous option labels when context is important.
 - **Don't** use `hide-label` without an accessible name.
 
+## Integration examples
+
+See [accessibility integration examples](./accessibility.md) for paired anti-pattern and recommended implementations.
+
 ## API
 
 ### Properties
@@ -137,7 +141,7 @@ Allowed parents: `p-multi-select`, `p-optgroup`.
 | Property | Type | Default | Description |
 | --- | --- | --- | --- |
 | `disabled` | `boolean` | `false` | Disables the option, preventing it from being selected. |
-| `value` _(required)_ | `string | number` | `undefined` | Sets the value submitted with the form data when this option is selected in the parent multi-select. |
+| `value` _(required)_ | `string | number` | `undefined` | Sets the required option value submitted with the form data when selected. Must be a string or number. |
 
 #### Slots