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

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

@@ -79,6 +79,10 @@ Due to the nature of **Web Components** and **shadow DOM**, there are limitation
 | `aria-labelledby` | 🚫 |
 | `aria-describedby` | 🚫 |
 
+## 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-link/accessibility.md

@@ -0,0 +1,73 @@
+# p-link accessibility integration examples
+
+## Integration examples
+
+### ARIA on component host vs aria prop
+
+#### ❌ Anti-pattern
+
+```html
+<p-link href="https://porsche.com" aria-label="Details of product XYZ">
+  Details
+</p-link>
+```
+
+#### ✅ Recommended
+
+```html
+<p-link href="https://porsche.com" [aria]="{'aria-label': 'Details of product XYZ'}">
+  Details
+</p-link>
+```
+
+### Icon-only link without accessible name
+
+#### ❌ Anti-pattern
+
+```html
+<p-link icon="arrow-right" href="https://porsche.com"></p-link>
+```
+
+#### ✅ Recommended
+
+```html
+<p-link icon="arrow-right" [hideLabel]="true" href="https://porsche.com">
+  Product details
+</p-link>
+```
+
+### Indicating the current page
+
+#### ❌ Anti-pattern
+
+```html
+<p-link href="/models/911" aria-current="page">
+  911
+</p-link>
+```
+
+#### ✅ Recommended
+
+```html
+<p-link href="/models/911" [aria]="{'aria-current': 'page'}">
+  911 Carrera
+</p-link>
+```
+
+### Vague link label without context
+
+#### ❌ Anti-pattern
+
+```html
+<p-link href="https://porsche.com">
+  Show
+</p-link>
+```
+
+#### ✅ Recommended
+
+```html
+<p-link href="https://porsche.com" [aria]="{'aria-label': 'Show details of product XYZ'}">
+  Show details
+</p-link>
+```

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

@@ -69,6 +69,10 @@ If the text of a link does not clearly indicate what the link's target is, add a
 - **Don't** add native `aria-*` attributes directly on the component host.
 - **Don't** rely on short generic link labels like "Show" or "Add" without context.
 
+## Integration examples
+
+See [accessibility integration examples](./accessibility.md) for paired anti-pattern and recommended implementations.
+
 ## API
 
 ### Properties
@@ -80,7 +84,7 @@ If the text of a link does not clearly indicate what the link's target is, add a
 | `download` | `string` | `undefined` | Sets the native `download` attribute to trigger a file download. Only applies when `href` is set. |
 | `hideLabel` | `boolean`<br>`BreakpointCustomizable<boolean>` | `false` | Hides the visible label while keeping it accessible to screen readers. Supports responsive breakpoint values. |
 | `href` | `string` | `undefined` | When set, the component renders as an anchor navigating to this URL. Otherwise, provide a slotted anchor element. |
-| `icon` | `'none'`<br>one of 290 icon names — see [icon names](references/icons.md) | `'none'` | Sets the icon displayed next to the link label. Use `none` to show no icon. |
+| `icon` | `'none'`<br>one of 293 icon names — see [icon names](references/icons.md) | `'none'` | Sets the icon displayed next to the link label. Use `none` to show no icon. |
 | `iconSource` | `string` | `undefined` | Sets a path to a custom SVG icon, used instead of the built-in icon set. |
 | `rel` | `string` | `undefined` | Sets the `rel` attribute on the link (e.g. `noopener`). Only applies when `href` is set. |
 | `target` | `'_self'` `'_blank'` `'_parent'` `'_top'` `'string'` | `'_self'` | Specifies where to open the linked URL (e.g. `_self`, `_blank`). Only applies when `href` is set. |

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

@@ -0,0 +1,73 @@
+# p-link-pure accessibility integration examples
+
+## Integration examples
+
+### ARIA on component host vs aria prop
+
+#### ❌ Anti-pattern
+
+```html
+<p-link-pure href="https://porsche.com" aria-label="Details of product XYZ">
+  Details
+</p-link-pure>
+```
+
+#### ✅ Recommended
+
+```html
+<p-link-pure href="https://porsche.com" [aria]="{'aria-label': 'Details of product XYZ'}">
+  Details
+</p-link-pure>
+```
+
+### Icon-only link without accessible name
+
+#### ❌ Anti-pattern
+
+```html
+<p-link-pure icon="arrow-right" href="https://porsche.com"></p-link-pure>
+```
+
+#### ✅ Recommended
+
+```html
+<p-link-pure icon="arrow-right" [hideLabel]="true" href="https://porsche.com">
+  Product details
+</p-link-pure>
+```
+
+### Indicating the current page
+
+#### ❌ Anti-pattern
+
+```html
+<p-link-pure href="/models/911" aria-current="page">
+  911
+</p-link-pure>
+```
+
+#### ✅ Recommended
+
+```html
+<p-link-pure href="/models/911" [aria]="{'aria-current': 'page'}">
+  911 Carrera
+</p-link-pure>
+```
+
+### Vague link label without context
+
+#### ❌ Anti-pattern
+
+```html
+<p-link-pure href="https://porsche.com">
+  Show
+</p-link-pure>
+```
+
+#### ✅ Recommended
+
+```html
+<p-link-pure href="https://porsche.com" [aria]="{'aria-label': 'Show details of product XYZ'}">
+  Show details
+</p-link-pure>
+```

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

@@ -72,6 +72,10 @@ If the text of a link does not clearly indicate what the link's target is, add a
 - **Don't** add native `aria-*` attributes directly on the component host.
 - **Don't** rely on short generic link labels like "Show" or "Add" without context.
 
+## Integration examples
+
+See [accessibility integration examples](./accessibility.md) for paired anti-pattern and recommended implementations.
+
 ## API
 
 ### Properties
@@ -85,7 +89,7 @@ If the text of a link does not clearly indicate what the link's target is, add a
 | `download` | `string` | `undefined` | Sets the native `download` attribute to trigger a file download. Only applies when `href` is set. |
 | `hideLabel` | `boolean`<br>`BreakpointCustomizable<boolean>` | `false` | Hides the visible label while keeping it accessible to screen readers. Supports responsive breakpoint values. |
 | `href` | `string` | `undefined` | When set, the component renders as an anchor navigating to this URL. Otherwise, provide a slotted anchor element. |
-| `icon` | `''`<br>one of 290 icon names — see [icon names](references/icons.md) | `'arrow-right'` | Sets the icon displayed next to the label. |
+| `icon` | `''`<br>one of 293 icon names — see [icon names](references/icons.md) | `'arrow-right'` | Sets the icon displayed next to the label. |
 | `iconSource` | `string` | `undefined` | Sets a path to a custom SVG icon, used instead of the built-in icon set. |
 | `rel` | `string` | `undefined` | Sets the `rel` attribute on the link (e.g. `noopener`). Only applies when `href` is set. |
 | `size` | `'2xs'` `'xs'` `'sm'` `'md'` `'lg'` `'xl'` `'2xl'` `'3xl'` `'4xl'` `'5xl'` `'inherit'`<br>_deprecated:_ `'xx-small'` `'x-small'` `'small'` `'medium'` `'large'` `'x-large'`<br>`BreakpointCustomizable<LinkPureSize>` | `'sm'` | Sets the font size of the link label. Supports responsive breakpoint values. |

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

@@ -0,0 +1,31 @@
+# p-link-tile accessibility integration examples
+
+## Integration examples
+
+### ARIA on component host vs aria prop
+
+#### ❌ Anti-pattern
+
+```html
+<p-link-tile label="Details" href="#" aria-label="Details of Porsche Taycan"></p-link-tile>
+```
+
+#### ✅ Recommended
+
+```html
+<p-link-tile label="Details" href="#" [aria]="{'aria-label': 'Details of Porsche Taycan'}"></p-link-tile>
+```
+
+### Vague link label without context
+
+#### ❌ Anti-pattern
+
+```html
+<p-link-tile label="Details" href="#"></p-link-tile>
+```
+
+#### ✅ Recommended
+
+```html
+<p-link-tile label="Porsche Taycan details" href="#"></p-link-tile>
+```

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

@@ -65,6 +65,10 @@ If the text of a link does not clearly indicate what the link's target is, add a
 - **Do** add `aria-label` on slotted `<video>` elements used as backgrounds.
 - **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-modal/accessibility.md

@@ -0,0 +1,80 @@
+# p-modal accessibility integration examples
+
+## Integration examples
+
+### ARIA on component host vs aria prop
+
+#### ❌ Anti-pattern
+
+```html
+<p-button aria-haspopup="dialog">
+  Details of product XYZ
+</p-button>
+```
+
+#### ✅ Recommended
+
+```html
+<p-button [aria]="{'aria-haspopup': 'dialog'}">
+  Details of product XYZ
+</p-button>
+```
+
+### Dialog label on component host vs header slot
+
+#### ❌ Anti-pattern
+
+```html
+<p-modal aria-label="Details">
+  ...
+</p-modal>
+```
+
+#### ✅ Recommended
+
+```html
+<p-modal>
+  <p-heading slot="header" tag="h2" size="lg">
+    Details of product XYZ
+  </p-heading>
+  ...
+</p-modal>
+
+<!-- or with aria prop when no visible header is shown -->
+
+<p-modal [aria]="{'aria-label': 'Details of product XYZ'}">
+  ...
+</p-modal>
+```
+
+### Modal trigger without popup semantics or context
+
+#### ❌ Anti-pattern
+
+```html
+<p-button>
+  Open
+</p-button>
+
+<p-modal>
+  <p-heading slot="header" tag="h2" size="lg">
+    Details
+  </p-heading>
+  ...
+</p-modal>
+```
+
+#### ✅ Recommended
+
+```html
+<p-button [aria]="{'aria-haspopup': 'dialog'}">
+  Details of product XYZ
+</p-button>
+
+<p-modal>
+  <p-heading slot="header" tag="h2" size="lg">
+    Details of product XYZ
+  </p-heading>
+  ...
+</p-modal>
+```

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

@@ -80,6 +80,10 @@ To inform users that the trigger button opens a `dialog`, the `aria-haspopup` at
 - **Don't** add raw host-level ARIA attributes as a workaround.
 - **Don't** use unclear trigger copy like "Open" when the destination is not obvious.
 
+## 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-multi-select/accessibility.md

@@ -0,0 +1,78 @@
+# p-multi-select accessibility integration examples
+
+## Integration examples
+
+### Prompt option used instead of a label
+
+#### ❌ Anti-pattern
+
+```html
+<p-multi-select name="features">
+  <p-multi-select-option value="">
+    Select features
+  </p-multi-select-option>
+  <p-multi-select-option value="sport">
+    Sport Chrono Package
+  </p-multi-select-option>
+</p-multi-select>
+```
+
+#### ✅ Recommended
+
+```html
+<p-multi-select label="Optional features" name="features" description="Select all features for your configuration.">
+  <p-multi-select-option value="sport">
+    Sport Chrono Package
+  </p-multi-select-option>
+  <p-multi-select-option value="audio">
+    BOSE Surround Sound
+  </p-multi-select-option>
+</p-multi-select>
+```
+
+### Hidden label without accessible name
+
+#### ❌ Anti-pattern
+
+```html
+<p-multi-select name="features" [hideLabel]="true">
+  <p-multi-select-option value="sport">
+    Sport Chrono Package
+  </p-multi-select-option>
+</p-multi-select>
+```
+
+#### ✅ Recommended
+
+```html
+<p-multi-select label="Optional features" name="features" [hideLabel]="true">
+  <p-multi-select-option value="sport">
+    Sport Chrono Package
+  </p-multi-select-option>
+</p-multi-select>
+```
+
+### Validation feedback via state and message API
+
+#### ❌ Anti-pattern
+
+```html
+<p-multi-select label="Optional features" name="features" [aria-invalid]="true" message="Required">
+  <p-multi-select-option value="sport">
+    Sport Chrono Package
+  </p-multi-select-option>
+</p-multi-select>
+```
+
+#### ✅ Recommended
+
+```html
+<p-multi-select label="Optional features" name="features" [required]="true" state="error" message="Select at least one feature to continue.">
+  <p-multi-select-option value="sport">
+    Sport Chrono Package
+  </p-multi-select-option>
+  <p-multi-select-option value="audio">
+    BOSE Surround Sound
+  </p-multi-select-option>
+</p-multi-select>
+```

package/{skill → skills/pds-knowledge-angular}/references/components/p-multi-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-multi-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-multi-select/examples/Form.ts

@@ -1,6 +1,6 @@
 import { ChangeDetectionStrategy, Component } from '@angular/core';
-import { FormControl, FormGroup, FormsModule, ReactiveFormsModule, Validators } from '@angular/forms';
-import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+import { FormControl, FormGroup, FormsModule, ReactiveFormsModule } from '@angular/forms';
+import { type PMultiSelectProps, PorscheDesignSystemModule } 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({
-    myMultiSelect: new FormControl<string[]>([]),
+    myMultiSelect: new FormControl<PMultiSelectProps['value']>([]),
   });
 
   submittedValue: any = undefined;

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

@@ -1,7 +1,7 @@
 import { ChangeDetectionStrategy, Component } from '@angular/core';
 import {
   type MultiSelectChangeEventDetail,
-  PMultiSelect,
+  type PMultiSelectProps,
   PorscheDesignSystemModule,
 } from '@porsche-design-system/components-angular';
 
@@ -87,7 +87,7 @@ const optionsData: Option[] = [
   imports: [PorscheDesignSystemModule],
 })
 export class ExampleComponent {
-  value: PMultiSelect['value'] = [];
+  value: PMultiSelectProps['value'] = [];
   options: Option[] = optionsData;
   selectedOptions: Option[] = [];
 

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

@@ -4,7 +4,7 @@ The `p-multi-select` component is a versatile custom form element that facilitat
 
 Many of the properties closely resemble those found in the [select](../p-select/p-select.md) and other form components (e.g. `label`, `description`, `state`, `message`, `hideLabel`, `disabled`, `required` & `dropdownDirection`). The `p-multi-select` offers a search field by default. When the user types in a search string, the options are reduced by matching the options text.
 
-Options are slotted using the `p-multi-select-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-multi-select` component ([More Info](./p-multi-select.md)). Options don't have a selected attribute or property. If an option should be visible but not selectable, it can be disabled by using the `disabled` attribute.
+Options are slotted using the `p-multi-select-option` component. Each option needs to have an assigned value, which can be passed via an attribute or property and needs to be a string or number. `null` and `undefined` are not valid option values. Initial selection states can only be achieved using the value property on the `p-multi-select` component ([More Info](./p-multi-select.md)). Options don't have a selected attribute or property. If an option should be visible but not selectable, it can be disabled by using the `disabled` attribute.
 
 **Hint:** The `p-multi-select` utilizes the [Popover API](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) to render its dropdown on the `#top-layer` which enables it to be shown correctly even when used e.g. within a scroll container.
 
@@ -85,6 +85,10 @@ In general, avoid using the `disabled` state. Disabled elements are no longer fo
 - **Don't** use a prompt option or adjacent text as a substitute for a field label.
 - **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
@@ -142,7 +146,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
 

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

@@ -0,0 +1,23 @@
+# p-pagination accessibility integration examples
+
+## Integration examples
+
+### Default English labels on a localized page
+
+#### ❌ Anti-pattern
+
+```html
+<html lang="de_DE">
+  ...
+  <p-pagination [totalItemsCount]="120" [itemsPerPage]="10" [activePage]="1"></p-pagination>
+</html>
+```
+
+#### ✅ Recommended
+
+```html
+<html lang="de_DE">
+  ...
+  <p-pagination [totalItemsCount]="120" [itemsPerPage]="10" [activePage]="1" [intl]="{'root': 'Seitennavigation', 'prev': 'Vorherige Seite', 'next': 'Nächste Seite', 'page': 'Seite'}"></p-pagination>
+</html>
+```

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

@@ -54,6 +54,10 @@ To adapt the pagination to the specific viewport context, the amount of displaye
 - **Do** keep prev/next and page button labels specific enough to identify the pagination control.
 - **Don't** rely on default English `intl` strings on localized pages.
 
+## 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-pin-code/accessibility.md

@@ -0,0 +1,45 @@
+# p-pin-code accessibility integration examples
+
+## Integration examples
+
+### Missing field label
+
+#### ❌ Anti-pattern
+
+```html
+<p-pin-code name="verification" [length]="6"></p-pin-code>
+```
+
+#### ✅ Recommended
+
+```html
+<p-pin-code name="verification" [length]="6" label="Verification code" description="Enter the 6-digit code from your email."></p-pin-code>
+```
+
+### Hidden label without accessible name
+
+#### ❌ Anti-pattern
+
+```html
+<p-pin-code name="verification" [length]="6" [hideLabel]="true"></p-pin-code>
+```
+
+#### ✅ Recommended
+
+```html
+<p-pin-code name="verification" [length]="6" [hideLabel]="true" label="Verification code"></p-pin-code>
+```
+
+### Validation feedback via state and message API
+
+#### ❌ Anti-pattern
+
+```html
+<p-pin-code name="verification" label="Verification code" [aria-invalid]="true" message="Invalid"></p-pin-code>
+```
+
+#### ✅ Recommended
+
+```html
+<p-pin-code name="verification" [length]="6" label="Verification code" state="error" message="Enter the complete 6-digit verification code."></p-pin-code>
+```

package/{skill → skills/pds-knowledge-angular}/references/components/p-pin-code/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, PPinCodeProps } from '@porsche-design-system/components-angular';
 
 @Component({
   selector: 'porsche-design-system-app',
@@ -20,7 +20,7 @@ import { PorscheDesignSystemModule } from '@porsche-design-system/components-ang
 })
 export class ExampleComponent {
   form = new FormGroup({
-    myPinCode: new FormControl<string>(''),
+    myPinCode: new FormControl<PPinCodeProps['value']>(''),
   });
 
   submittedValue: any = undefined;