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

package/skills/pds-knowledge-react/references/components/p-banner/accessibility.md

@@ -0,0 +1,37 @@
+# p-banner accessibility integration examples
+
+## Integration examples
+
+### Banner mounted only when shown
+
+#### ❌ Anti-pattern
+
+```tsx
+{hasError && (
+  <PBanner open heading="Error">
+    Something went wrong.
+  </PBanner>
+)}
+```
+
+#### ✅ Recommended
+
+```tsx
+{/* Pre-render the banner and update content when needed. */}
+
+<PBanner id="form-banner" heading="Error" description="Check the highlighted fields and try again." state="error"></PBanner>
+```
+
+### Error feedback without descriptive content
+
+#### ❌ Anti-pattern
+
+```tsx
+<PBanner open={true} state="error" description="Error"></PBanner>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PBanner open={true} state="error" heading="Payment could not be processed" description="Check your card details or try another payment method."></PBanner>
+```

package/{skill → skills/pds-knowledge-react}/references/components/p-banner/p-banner.md

@@ -43,6 +43,10 @@ The `Banner` component uses `role="status"` and `role="alert"` to announce **con
 - **Do** return focus to the trigger or at a logical place after the banner is dismissed.
 - **Don't** mount the entire banner only at the moment it should be announced.
 
+## Integration examples
+
+See [accessibility integration examples](./accessibility.md) for paired anti-pattern and recommended implementations.
+
 ## API
 
 ### Properties

package/skills/pds-knowledge-react/references/components/p-button/accessibility.md

@@ -0,0 +1,61 @@
+# p-button accessibility integration examples
+
+## Integration examples
+
+### ARIA on component host vs aria prop
+
+#### ❌ Anti-pattern
+
+```tsx
+<PButton aria-haspopup="dialog" aria-label="Open details of product XYZ">
+  Open details
+</PButton>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PButton aria={{'aria-haspopup': 'dialog', 'aria-label': 'Open details of product XYZ'}}>
+  Open details
+</PButton>
+```
+
+### Icon-only button without accessible name
+
+#### ❌ Anti-pattern
+
+```tsx
+<PButton icon="plus"></PButton>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PButton icon="plus" hideLabel={true}>
+  Add item XYZ to shopping cart
+</PButton>
+```
+
+### Vague button label without context
+
+#### ❌ Anti-pattern
+
+```tsx
+<PButton icon="plus">
+  Add
+</PButton>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PButton icon="plus" aria={{'aria-label': 'Add item XYZ to shopping cart'}}>
+  Add
+</PButton>
+
+{/* or use descriptive visible text */}
+
+<PButton icon="plus">
+  Add item XYZ to cart
+</PButton>
+```

package/{skill → skills/pds-knowledge-react}/references/components/p-button/p-button.md

@@ -84,6 +84,10 @@ If the text of a button does not clearly indicate what the button's behavior is,
 - **Don't** add native `aria-*` attributes directly on the component host.
 - **Don't** rely on short generic button labels like "Show" or "Add" without context.
 
+## Integration examples
+
+See [accessibility integration examples](./accessibility.md) for paired anti-pattern and recommended implementations.
+
 ## API
 
 ### Properties
@@ -95,7 +99,7 @@ If the text of a button does not clearly indicate what the button's behavior is,
 | `disabled` | `boolean` | `false` | Disables the button, preventing all interaction and blocking events. |
 | `form` | `string` | `undefined` | Associates the button with a form element by its ID, so it can submit or reset that form even when placed outside of it. |
 | `hideLabel` | `boolean`<br>`BreakpointCustomizable<boolean>` | `false` | Hides the visible label while keeping it accessible to screen readers. Supports responsive breakpoint values. |
-| `icon` | `'none'`<br>one of 290 icon names — see [icon names](references/icons.md) | `'none'` | Sets the icon displayed inside the button. 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 inside the button. 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. |
 | `loading` | `boolean` | `false` | Disables the button and replaces its content with a loading spinner to indicate an ongoing operation. |
 | `name` | `string` | `undefined` | Sets the name submitted with the form data when this button triggers form submission. |

package/skills/pds-knowledge-react/references/components/p-button-pure/accessibility.md

@@ -0,0 +1,61 @@
+# p-button-pure accessibility integration examples
+
+## Integration examples
+
+### ARIA on component host vs aria prop
+
+#### ❌ Anti-pattern
+
+```tsx
+<PButtonPure aria-haspopup="dialog" aria-label="Open details of product XYZ">
+  Open details
+</PButtonPure>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PButtonPure aria={{'aria-haspopup': 'dialog', 'aria-label': 'Open details of product XYZ'}}>
+  Open details
+</PButtonPure>
+```
+
+### Icon-only button without accessible name
+
+#### ❌ Anti-pattern
+
+```tsx
+<PButtonPure icon="plus"></PButtonPure>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PButtonPure icon="plus" hideLabel={true}>
+  Add item XYZ to shopping cart
+</PButtonPure>
+```
+
+### Vague button label without context
+
+#### ❌ Anti-pattern
+
+```tsx
+<PButtonPure icon="plus">
+  Add
+</PButtonPure>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PButtonPure icon="plus" aria={{'aria-label': 'Add item XYZ to shopping cart'}}>
+  Add
+</PButtonPure>
+
+{/* or use descriptive visible text */}
+
+<PButtonPure icon="plus">
+  Add item XYZ to cart
+</PButtonPure>
+```

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

@@ -79,6 +79,10 @@ If the text of a button does not clearly indicate what the button's behavior is,
 - **Don't** add native `aria-*` attributes directly on the component host.
 - **Don't** rely on short generic button labels like "Show" or "Add" without context.
 
+## Integration examples
+
+See [accessibility integration examples](./accessibility.md) for paired anti-pattern and recommended implementations.
+
 ## API
 
 ### Properties
@@ -92,7 +96,7 @@ If the text of a button does not clearly indicate what the button's behavior is,
 | `disabled` | `boolean` | `false` | Disables the button, preventing all interaction and blocking events. |
 | `form` | `string` | `undefined` | Associates the button with a form element by its ID, so it can submit or reset that form even when placed outside of it. |
 | `hideLabel` | `boolean`<br>`BreakpointCustomizable<boolean>` | `false` | Hides the visible label while keeping it accessible to screen readers. Supports responsive breakpoint values. |
-| `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. |
 | `loading` | `boolean` | `false` | Disables the button and replaces its icon with a loading spinner to indicate an ongoing operation. |
 | `name` | `string` | `undefined` | Sets the name submitted with the form data when this button triggers form submission. |

package/skills/pds-knowledge-react/references/components/p-button-tile/accessibility.md

@@ -0,0 +1,31 @@
+# p-button-tile accessibility integration examples
+
+## Integration examples
+
+### ARIA on component host vs aria prop
+
+#### ❌ Anti-pattern
+
+```tsx
+<PButtonTile label="Open" aria-label="Open details of Porsche Taycan" aria-haspopup="dialog"></PButtonTile>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PButtonTile label="Open" aria={{'aria-haspopup': 'dialog', 'aria-label': 'Open details of Porsche Taycan'}}></PButtonTile>
+```
+
+### Vague tile label without context
+
+#### ❌ Anti-pattern
+
+```tsx
+<PButtonTile label="Open"></PButtonTile>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PButtonTile label="Configure Porsche Taycan"></PButtonTile>
+```

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

@@ -75,6 +75,10 @@ If the text of the button does not clearly indicate what the button's function i
 - **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
@@ -88,7 +92,7 @@ If the text of the button does not clearly indicate what the button's function i
 | `description` _(required)_ | `string` | `undefined` | Sets the description text displayed in the tile's content area. |
 | `disabled` | `boolean` | `false` | Disables the tile, preventing button interaction. |
 | `gradient` | `boolean` | `false` | Shows a gradient overlay over the media slot to improve text legibility on bright images or videos. |
-| `icon` | `'none'`<br>one of 290 icon names — see [icon names](references/icons.md) | `'none'` | Sets the icon displayed in the tile's action button. 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 in the tile's action button. Use `none` to show no icon. |
 | `iconSource` | `string` | `undefined` | Sets a path to a custom SVG icon for the action button, used instead of the built-in icon set. |
 | `label` _(required)_ | `string` | `undefined` | Sets the accessible label text of the action button rendered inside the tile. |
 | `loading` | `boolean` | `false` | Disables the tile and shows a loading spinner to indicate an ongoing operation. |

package/skills/pds-knowledge-react/references/components/p-canvas/examples/Default.tsx

@@ -0,0 +1,111 @@
+import React from 'react';
+import {
+  type CanvasSidebarStartUpdateEventDetail,
+  PButton,
+  PCanvas,
+  PHeading,
+  PText,
+} from '@porsche-design-system/components-react';
+import { breakpointS } from '@porsche-design-system/components-react/emotion';
+import { useCallback, useState } from 'react';
+
+export const Example = () => {
+  const [isSidebarStartOpen, setIsSidebarStartOpen] = useState<boolean>(
+    // initially, sidebar should be closed on mobile and opened on desktop
+    window.matchMedia(`(min-width: ${breakpointS}px)`).matches
+  );
+  const [isSidebarEndOpen, setIsSidebarEndOpen] = useState<boolean>(false);
+
+  const onSidebarStartUpdate = useCallback((e: CustomEvent<CanvasSidebarStartUpdateEventDetail>) => {
+    setIsSidebarStartOpen(e.detail.open);
+  }, []);
+  const onSidebarEndOpen = useCallback(() => {
+    setIsSidebarEndOpen(true);
+  }, []);
+  const onSidebarEndDismiss = useCallback(() => {
+    setIsSidebarEndOpen(false);
+  }, []);
+
+  const style = `
+      .-col-span-full-1 {
+        grid-column: 1 / -1;
+      }
+
+      .-col-span-full-2 {
+        grid-column: 2 / -2;
+      }
+
+      .-col-span-full-3 {
+        grid-column: 3 / -3;
+      }
+
+      .-col-span-4 {
+        grid-column: span 4;
+      }
+
+      .tile {
+        margin-top: 16px;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        padding: 16px;
+        background: lightpink;
+      }
+  `;
+
+  return (
+    <>
+      <style dangerouslySetInnerHTML={{ __html: style }} />
+      <PCanvas
+        sidebarStartOpen={isSidebarStartOpen}
+        sidebarEndOpen={isSidebarEndOpen}
+        onSidebarStartUpdate={onSidebarStartUpdate}
+        onSidebarEndDismiss={onSidebarEndDismiss}
+      >
+        <a slot="title" href="#">
+          App Name
+        </a>
+
+        <PButton
+          slot="header-end"
+          icon="configurate"
+          variant="secondary"
+          compact={true}
+          hideLabel={true}
+          onClick={onSidebarEndOpen}
+        >
+          Open sidebar
+        </PButton>
+
+        <div className="-p-canvas-grid">
+          <PText className="-col-span-full-1">Content</PText>
+
+          <div className="tile -col-span-4">Grid span 4x</div>
+          <div className="tile -col-span-4">Grid span 4x</div>
+          <div className="tile -col-span-4">Grid span 4x</div>
+
+          <div className="tile -col-span-full-1">12 Grid columns</div>
+          <div className="tile -col-span-full-2">10 Grid columns</div>
+          <div className="tile -col-span-full-3">8 Grid columns</div>
+        </div>
+
+        <div slot="footer" className="-p-canvas-grid">
+          <PText className="-col-span-full-1">Footer</PText>
+          <div className="tile -col-span-full-1">12 Grid columns</div>
+        </div>
+
+        <div slot="sidebar-start">
+          <PText>Sidebar Start</PText>
+        </div>
+
+        <PHeading slot="sidebar-end-header" tag="h2" size="small">
+          Sidebar End Header
+        </PHeading>
+
+        <div slot="sidebar-end">
+          <PText>Sidebar End</PText>
+        </div>
+      </PCanvas>
+    </>
+  );
+};

package/{skill → skills/pds-knowledge-react}/references/components/p-canvas/p-canvas.md

@@ -10,6 +10,10 @@ The canvas component provides a CSS utility class which comes with a basic 12 co
 .-p-canvas-grid // experimental, might be removed in a future release
 ```
 
+> **Porsche Grid compatibility**
+>
+> The standard Porsche Grid currently supports only top-level layouts that span the full viewport width. Do not use it inside the `p-canvas` default or footer slots because their available width can be reduced by open sidebars. Use `.-p-canvas-grid` instead.
+
 The canvas component has some values which can be overwritten by **CSS Variables**.
 
 ```scss

package/skills/pds-knowledge-react/references/components/p-carousel/accessibility.md

@@ -0,0 +1,61 @@
+# p-carousel accessibility integration examples
+
+## Integration examples
+
+### ARIA on component host vs aria prop
+
+#### ❌ Anti-pattern
+
+```tsx
+<PCarousel aria-label="Slider">
+  {/* slides */}
+</PCarousel>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PCarousel aria={{'aria-label': 'Featured Porsche models'}}>
+  {/* slides */}
+</PCarousel>
+```
+
+### Carousel without skip path for keyboard users
+
+#### ❌ Anti-pattern
+
+```tsx
+<PCarousel>
+  {/* many slides (>6 items) */}
+</PCarousel>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PCarousel skipLinkTarget="#after-carousel" aria={{'aria-label': 'Highlights'}}>
+  {/* many slides (>6 items) */}
+</PCarousel>
+
+<PHeading tag="h2" id="after-carousel">
+  Next section
+</PHeading>
+```
+
+### Vague carousel label
+
+#### ❌ Anti-pattern
+
+```tsx
+<PCarousel aria={{'aria-label': 'Slider'}}>
+  {/* slides */}
+</PCarousel>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PCarousel aria={{'aria-label': 'Featured Porsche models'}}>
+  {/* slides */}
+</PCarousel>
+```

package/{skill → skills/pds-knowledge-react}/references/components/p-carousel/p-carousel.md

@@ -59,7 +59,7 @@ Therefore, the `p-carousel`'s content has to be divided into multiple parts or s
 | `aria-labelledby="IDREF"` | References the accessible name. |
 | `aria-roledescription="carousel"` | Specifies the role as "carousel". |
 | `aria-roledescription="slide"` | Specifies the role of the carousel item as "slide". |
-| `aria-live="polite"` | Announces current active slide item. |
+| `aria-live="polite"` | Announces page position after control-driven movement (prev/next, pagination, drag), e.g. "2 of 8" via `intl.slideLabel`. Not announced when navigating by focusing slides. |
 
 ## Development considerations
 
@@ -78,6 +78,10 @@ Through the `skipLinkTarget` property, a skip link for keyboard users can be pro
 - **Don't** force keyboard users to tab through every slide control when a skip path is needed.
 - **Don't** use vague labels that do not communicate carousel context.
 
+## Integration examples
+
+See [accessibility integration examples](./accessibility.md) for paired anti-pattern and recommended implementations.
+
 ## API
 
 ### Properties

package/skills/pds-knowledge-react/references/components/p-checkbox/accessibility.md

@@ -0,0 +1,31 @@
+# p-checkbox accessibility integration examples
+
+## Integration examples
+
+### Hidden label without accessible name
+
+#### ❌ Anti-pattern
+
+```tsx
+<PCheckbox name="terms" hideLabel={true}></PCheckbox>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PCheckbox name="terms" hideLabel={true} label="I accept the terms and conditions"></PCheckbox>
+```
+
+### Validation feedback via state and message API
+
+#### ❌ Anti-pattern
+
+```tsx
+<PCheckbox name="terms" label="I accept the terms and conditions" aria-invalid={true} message="Required"></PCheckbox>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PCheckbox name="terms" label="I accept the terms and conditions" required={true} state="error" message="Accept the terms and conditions to continue."></PCheckbox>
+```

package/{skill → skills/pds-knowledge-react}/references/components/p-checkbox/p-checkbox.md

@@ -68,6 +68,10 @@ In general, avoid using the `disabled` state. Disabled elements are no longer fo
 - **Don't** use `hide-label` without an accessible name.
 - **Don't** use `hide-label` when it is not clear what the checkbox controls.
 
+## Integration examples
+
+See [accessibility integration examples](./accessibility.md) for paired anti-pattern and recommended implementations.
+
 ## API
 
 ### Properties

package/skills/pds-knowledge-react/references/components/p-crest/accessibility.md

@@ -0,0 +1,17 @@
+# p-crest accessibility integration examples
+
+## Integration examples
+
+### ARIA on component host vs aria prop
+
+#### ❌ Anti-pattern
+
+```tsx
+<PCrest href="/" aria-label="Porsche home"></PCrest>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PCrest href="/" aria={{'aria-label': 'Porsche home'}}></PCrest>
+```

package/{skill → skills/pds-knowledge-react}/references/components/p-crest/p-crest.md

@@ -46,6 +46,10 @@ You can use native `click`, `focus`, `focusin`, `blur` and `focusout` events on
 - **Do** provide a descriptive `aria-label` for linked crests, for example "Porsche home".
 - **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-react/references/components/p-divider/accessibility.md

@@ -0,0 +1,41 @@
+# p-divider accessibility integration examples
+
+## Integration examples
+
+### Divider as the only section separator
+
+#### ❌ Anti-pattern
+
+```tsx
+<PText>
+  Delivery details
+</PText>
+
+<PDivider></PDivider>
+
+<PText>
+  Payment details
+</PText>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PHeading tag="h2" size="md">
+  Delivery details
+</PHeading>
+
+<PText>
+  ...
+</PText>
+
+<PDivider></PDivider>
+
+<PHeading tag="h2" size="md">
+  Payment details
+</PHeading>
+
+<PText>
+  ...
+</PText>
+```

package/{skill → skills/pds-knowledge-react}/references/components/p-divider/p-divider.md

@@ -31,6 +31,10 @@ A divider is visual separation only. Use headings, landmarks, or section structu
 - **Do** pair dividers with headings or landmarks that describe the sections they separate.
 - **Don't** rely on a divider alone to communicate a new major section.
 
+## Integration examples
+
+See [accessibility integration examples](./accessibility.md) for paired anti-pattern and recommended implementations.
+
 ## API
 
 ### Properties

package/skills/pds-knowledge-react/references/components/p-drilldown/accessibility.md

@@ -0,0 +1,65 @@
+# p-drilldown accessibility integration examples
+
+## Integration examples
+
+### ARIA on trigger button host vs aria prop
+
+#### ❌ Anti-pattern
+
+```tsx
+<PButton aria-haspopup="dialog">
+  Menu
+</PButton>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PButton aria={{'aria-haspopup': 'dialog'}}>
+  Vehicle menu
+</PButton>
+```
+
+### Drilldown label on component host vs aria prop
+
+#### ❌ Anti-pattern
+
+```tsx
+<PDrilldown open={true} aria-label="Navigation">
+  ...
+</PDrilldown>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PDrilldown open={true} aria={{'aria-label': 'Vehicle navigation'}}>
+  ...
+</PDrilldown>
+```
+
+### Trigger without popup semantics or context
+
+#### ❌ Anti-pattern
+
+```tsx
+<PButton>
+  Menu
+</PButton>
+
+<PDrilldown>
+  ...
+</PDrilldown>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PButton aria={{'aria-haspopup': 'dialog'}}>
+  Vehicle menu
+</PButton>
+
+<PDrilldown aria={{'aria-label': 'Vehicle navigation'}}>
+  ...
+</PDrilldown>
+```

package/{skill → skills/pds-knowledge-react}/references/components/p-drilldown/p-drilldown.md

@@ -74,6 +74,10 @@ To inform users that the trigger button opens a `dialog`, the `aria-haspopup` at
 - **Do** provide a meaningful dialog label through the drilldown `aria` prop when needed.
 - **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