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

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

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

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

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

@@ -75,6 +75,10 @@ Set `aria-haspopup` on the trigger so users know a dialog will open. Ensure the
 - **Don't** add raw host-level ARIA attributes as a workaround.
 - **Don't** use unclear trigger copy like "Open" when the sheet purpose 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-spinner/accessibility.md

@@ -0,0 +1,33 @@
+# p-spinner accessibility integration examples
+
+## Integration examples
+
+### Spinner mounted only when loading starts
+
+#### ❌ Anti-pattern
+
+```html
+@if (isLoading) {
+  <p-spinner></p-spinner>
+}
+```
+
+#### ✅ Recommended
+
+```html
+<p-spinner [aria]="{'aria-label': 'Loading vehicle configuration'}"></p-spinner>
+```
+
+### Spinner without loading message
+
+#### ❌ Anti-pattern
+
+```html
+<p-spinner></p-spinner>
+```
+
+#### ✅ Recommended
+
+```html
+<p-spinner [aria]="{'aria-label': 'Loading vehicle configuration'}"></p-spinner>
+```

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

@@ -54,6 +54,10 @@ To provide feedback to screen reader users, it is mandatory to announce the load
 - **Do** provide a specific loading message through the `aria` prop.
 - **Don't** mount the spinner only at the moment loading starts without a label.
 
+## Integration examples
+
+See [accessibility integration examples](./accessibility.md) for paired anti-pattern and recommended implementations.
+
 ## Notes
 
 ### Disable animation

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

@@ -0,0 +1,34 @@
+# p-stepper-horizontal accessibility integration examples
+
+## Integration examples
+
+### Generic step labels without context
+
+#### ❌ Anti-pattern
+
+```html
+<p-stepper-horizontal>
+  <p-stepper-horizontal-item state="complete">
+    Step 1
+  </p-stepper-horizontal-item>
+  <p-stepper-horizontal-item state="current">
+    Step 2
+  </p-stepper-horizontal-item>
+</p-stepper-horizontal>
+```
+
+#### ✅ Recommended
+
+```html
+<p-stepper-horizontal>
+  <p-stepper-horizontal-item state="complete">
+    Configure vehicle
+  </p-stepper-horizontal-item>
+  <p-stepper-horizontal-item state="current">
+    Choose delivery date
+  </p-stepper-horizontal-item>
+  <p-stepper-horizontal-item>
+    Review and confirm
+  </p-stepper-horizontal-item>
+</p-stepper-horizontal>
+```

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

@@ -60,6 +60,10 @@ By clicking on a previous step, the `p-stepper-horizontal` emits the `update` ev
 - **Do** reflect the current step with the item `state` prop (`current`, `complete`, `warning`).
 - **Don't** use generic labels like "Step 1" without describing the step purpose.
 
+## 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-switch/accessibility.md

@@ -0,0 +1,35 @@
+# p-switch accessibility integration examples
+
+## Integration examples
+
+### Switch without descriptive label
+
+#### ❌ Anti-pattern
+
+```html
+<p-switch name="notifications"></p-switch>
+```
+
+#### ✅ Recommended
+
+```html
+<p-switch name="notifications">
+  Email notifications for order updates
+</p-switch>
+```
+
+### Hidden label without accessible name
+
+#### ❌ Anti-pattern
+
+```html
+<p-switch name="notifications" [hideLabel]="true"></p-switch>
+```
+
+#### ✅ Recommended
+
+```html
+<p-switch name="notifications" [hideLabel]="true">
+  Email notifications for order updates
+</p-switch>
+```

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

@@ -66,6 +66,10 @@ The switch accessible name comes from the default slot. Provide concise, descrip
 - **Do** use `hide-label` only when the label text remains in the slot for screen readers.
 - **Don't** use an icon or visual state alone without descriptive label text.
 
+## 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-table/accessibility.md

@@ -0,0 +1,47 @@
+# p-table accessibility integration examples
+
+## Integration examples
+
+### Data table without caption
+
+#### ❌ Anti-pattern
+
+```html
+<p-table>
+  <p-table-head>
+    ...
+  </p-table-head>
+  <p-table-body>
+    ...
+  </p-table-body>
+</p-table>
+```
+
+#### ✅ Recommended
+
+```html
+<p-table caption="Available Porsche 911 models and starting prices">
+  <p-table-head>
+    ...
+  </p-table-head>
+  <p-table-body>
+    ...
+  </p-table-body>
+</p-table>
+```
+
+### Column with hidden label
+
+#### ❌ Anti-pattern
+
+```html
+<p-table-head-cell [hideLabel]="true"></p-table-head-cell>
+```
+
+#### ✅ Recommended
+
+```html
+<p-table-head-cell [hideLabel]="true">
+  Model
+</p-table-head-cell>
+```

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

@@ -20,21 +20,21 @@ const headSorting: HeadSorting[] = [
 
 type DataSorting = {
   col1: string;
-  col2: string;
+  col2: number;
   col3: string;
 };
 
 const dataSorting: DataSorting[] = [
-  {
-    col1: 'Name A',
-    col2: '9',
-    col3: '01.06.2021',
-  },
   {
     col1: 'Name Z',
-    col2: '1',
+    col2: 1,
     col3: '24.06.2021',
   },
+  {
+    col1: 'Name A',
+    col2: 9,
+    col3: '01.06.2021',
+  },
 ];
 
 @Component({
@@ -72,8 +72,9 @@ export class ExampleComponent {
   onUpdate(e: CustomEvent<TableUpdateEventDetail>): void {
     const { id, direction } = e.detail as TableUpdateEventDetail & { id: keyof DataSorting };
     this.head = this.head.map((item) => ({ ...item, active: false, ...(item.id === id && e.detail) }));
-    this.data = [...this.data].sort((a, b) =>
-      direction === 'asc' ? a[id].localeCompare(b[id]) : b[id].localeCompare(a[id])
-    );
+    this.data = [...this.data].sort((a, b) => {
+      const result = String(a[id]).localeCompare(String(b[id]), undefined, { numeric: true });
+      return direction === 'asc' ? result : -result;
+    });
   }
 }

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

@@ -50,6 +50,10 @@ It is a controlled component. This means it does not contain any internal state,
 - **Do** keep visible header text for sortable columns.
 - **Don't** use `hide-label` on a sortable column without an alternative accessible name.
 
+## Integration examples
+
+See [accessibility integration examples](./accessibility.md) for paired anti-pattern and recommended implementations.
+
 ## Tests
 
 ### Automated
@@ -184,6 +188,6 @@ Allowed parents: `p-table-body`, `p-table-head`.
 | Caption via Property | A caption that describes the content of the table is mandatory to fulfill accessibility criteria. | [./examples/CaptionProperty.ts](./examples/CaptionProperty.ts) |
 | Caption via Slot | Instead of using the the property, the table's caption can be provided via the `caption` slot. | [./examples/CaptionSlot.ts](./examples/CaptionSlot.ts) |
 | Layout: fixed | By setting `layout` to `fixed`, you can take full control over each column width, which would otherwise be controlled by its content. | [./examples/LayoutFixed.ts](./examples/LayoutFixed.ts) |
-| Sortable Columns | The `p-table`'s column headers can be configured by setting properties on each `p-table-head-cell`. | [./examples/Sorting.ts](./examples/Sorting.ts) |
+| Sortable Columns | Sorting is controlled, so the initial row order must match the active column's `direction` and both must remain synchronized when handling the `update` event. | [./examples/Sorting.ts](./examples/Sorting.ts) |
 | Hide Column Label | Sometimes you want to hide the visible label of a `p-table-head-cell`, for example when the column's content is self-explanatory. | [./examples/HideLabel.ts](./examples/HideLabel.ts) |
 | Advanced Table | The appearance of a table's contents can be customized as illustrated in the following example. | [./examples/Advanced.ts](./examples/Advanced.ts) |

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

@@ -0,0 +1,56 @@
+# p-tabs accessibility integration examples
+
+## Integration examples
+
+### ARIA on component host vs aria prop
+
+#### ❌ Anti-pattern
+
+```html
+<p-tabs aria-label="Product details">
+  <p-tabs-item label="Overview">
+    ...
+  </p-tabs-item>
+</p-tabs>
+```
+
+#### ✅ Recommended
+
+```html
+<p-tabs [aria]="{'aria-label': 'Porsche 911 configuration details'}">
+  <p-tabs-item label="Overview">
+    ...
+  </p-tabs-item>
+  <p-tabs-item label="Equipment">
+    ...
+  </p-tabs-item>
+</p-tabs>
+```
+
+### Vague tab labels without context
+
+#### ❌ Anti-pattern
+
+```html
+<p-tabs [aria]="{'aria-label': 'Product details'}">
+  <p-tabs-item label="Details">
+    ...
+  </p-tabs-item>
+  <p-tabs-item label="More">
+    ...
+  </p-tabs-item>
+</p-tabs>
+```
+
+#### ✅ Recommended
+
+```html
+<p-tabs [aria]="{'aria-label': 'Porsche 911 configuration details'}">
+  <p-tabs-item label="Overview">
+    ...
+  </p-tabs-item>
+  <p-tabs-item label="Equipment and packages">
+    ...
+  </p-tabs-item>
+</p-tabs>
+```

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

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

@@ -0,0 +1,61 @@
+# p-tabs-bar accessibility integration examples
+
+## Integration examples
+
+### Tabbed interface without tablist label
+
+#### ❌ Anti-pattern
+
+```html
+<p-tabs-bar [activeTabIndex]="0">
+  <button type="button" id="tab-0" ariaControls="panel-0">
+    Overview
+  </button>
+  <button type="button" id="tab-1" ariaControls="panel-1">
+    Equipment
+  </button>
+</p-tabs-bar>
+```
+
+#### ✅ Recommended
+
+```html
+<p-tabs-bar [aria]="{'aria-label': 'Porsche 911 configuration sections'}" [activeTabIndex]="0">
+  <button type="button" id="tab-0" ariaControls="panel-0">
+    Overview
+  </button>
+  <button type="button" id="tab-1" ariaControls="panel-1">
+    Equipment
+  </button>
+</p-tabs-bar>
+```
+
+### Route navigation without landmark label
+
+#### ❌ Anti-pattern
+
+```html
+<p-tabs-bar>
+  <a href="/models/911">
+    911
+  </a>
+  <a href="/models/taycan">
+    Taycan
+  </a>
+</p-tabs-bar>
+```
+
+#### ✅ Recommended
+
+```html
+<nav ariaLabel="Porsche model range">
+  <p-tabs-bar>
+    <a href="/models/911" ariaCurrent="page">
+      911
+    </a>
+    <a href="/models/taycan">
+      Taycan
+    </a>
+  </p-tabs-bar>
+</nav>
+```

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

@@ -142,6 +142,10 @@ If the `p-tabs-bar` is used as an in-page jump navigation, you should follow the
 - **Do** wire `aria-controls`, `role="tabpanel"`, and `aria-labelledby` in the host application for tab interfaces.
 - **Don't** add tab semantics when the component is used as a link list for route-based navigation.
 
+## 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-tag/accessibility.md

@@ -0,0 +1,19 @@
+# p-tag accessibility integration examples
+
+## Integration examples
+
+### Status conveyed by color and icon only
+
+#### ❌ Anti-pattern
+
+```html
+<p-tag variant="success" icon="check"></p-tag>
+```
+
+#### ✅ Recommended
+
+```html
+<p-tag variant="success" icon="check">
+  Configuration saved
+</p-tag>
+```

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

@@ -39,6 +39,10 @@ Tags should communicate status or category in visible text. Do not rely on color
 - **Do** use color and icon as supporting cues, not the only indicator.
 - **Don't** use an icon-only tag without visible text.
 
+## 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-tag-dismissible/accessibility.md

@@ -0,0 +1,35 @@
+# p-tag-dismissible accessibility integration examples
+
+## Integration examples
+
+### Dismiss button ARIA on host vs aria prop
+
+#### ❌ Anti-pattern
+
+```html
+<p-tag-dismissible label="Sport Chrono" aria-label="Remove Sport Chrono filter"></p-tag-dismissible>
+```
+
+#### ✅ Recommended
+
+```html
+<p-tag-dismissible label="Sport Chrono" [aria]="{'aria-label': 'Remove Sport Chrono filter'}"></p-tag-dismissible>
+```
+
+### Tag without descriptive label
+
+#### ❌ Anti-pattern
+
+```html
+<p-tag-dismissible>
+  <p-icon name="watch-sport-chrono"></p-icon>
+</p-tag-dismissible>
+```
+
+#### ✅ Recommended
+
+```html
+<p-tag-dismissible label="Sport Chrono Package">
+  <p-icon name="watch-sport-chrono"></p-icon>
+</p-tag-dismissible>
+```

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

@@ -52,6 +52,10 @@ Ensure that when a `p-tag-dismissible` is removed, the focus is set to the previ
 - **Do** move focus to a sensible target after removing a tag.
 - **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-text/accessibility.md

@@ -0,0 +1,21 @@
+# p-text accessibility integration examples
+
+## Integration examples
+
+### Heading tag used for styling only
+
+#### ❌ Anti-pattern
+
+```html
+<p-text tag="p" size="lg" weight="bold">
+  Delivery options
+</p-text>
+```
+
+#### ✅ Recommended
+
+```html
+<p-heading tag="h2" size="lg">
+  Delivery options
+</p-heading>
+```

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

@@ -38,6 +38,10 @@ Use the `tag` prop to choose the correct HTML element. Do not pick heading tags
 - **Do** evaluate correct semantic meaning, e.g. use `tag="p"` for regular paragraphs.
 - **Don't** nest text components.
 
+## 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-text-list/accessibility.md

@@ -0,0 +1,31 @@
+# p-text-list accessibility integration examples
+
+## Integration examples
+
+### Numbered list for non-sequential items
+
+#### ❌ Anti-pattern
+
+```html
+<p-text-list type="numbered">
+  <p-text-list-item>
+    Sport Chrono Package
+  </p-text-list-item>
+  <p-text-list-item>
+    BOSE Surround Sound
+  </p-text-list-item>
+</p-text-list>
+```
+
+#### ✅ Recommended
+
+```html
+<p-text-list type="unordered">
+  <p-text-list-item>
+    Sport Chrono Package
+  </p-text-list-item>
+  <p-text-list-item>
+    BOSE Surround Sound
+  </p-text-list-item>
+</p-text-list>
+```

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

@@ -33,6 +33,10 @@ Choose the list `type` based on whether item order matters to understanding the
 - **Do** use `type="numbered"` or `type="alphabetically"` when step order or ranking matters.
 - **Don't** use a numbered list for items that are not sequential.
 
+## Integration examples
+
+See [accessibility integration examples](./accessibility.md) for paired anti-pattern and recommended implementations.
+
 ## API
 
 ### Properties