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

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

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

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

@@ -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

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

@@ -0,0 +1,37 @@
+# p-fieldset accessibility integration examples
+
+## Integration examples
+
+### Unlabeled field group
+
+#### ❌ Anti-pattern
+
+```tsx
+<PFieldset>
+  <PInputText name="street" label="Street"></PInputText>
+  <PInputText name="city" label="City"></PInputText>
+</PFieldset>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PFieldset label="Delivery address">
+  <PInputText name="street" label="Street"></PInputText>
+  <PInputText name="city" label="City"></PInputText>
+</PFieldset>
+```
+
+### Error state without recovery guidance
+
+#### ❌ Anti-pattern
+
+```tsx
+<PFieldset label="Delivery address" state="error" message="Invalid"></PFieldset>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PFieldset label="Delivery address" required={true} state="error" message="Complete all required address fields to continue."></PFieldset>
+```

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

@@ -57,6 +57,10 @@ The `p-fieldset` is a grouping component for wrapping contextual associated form
 - **Do** use `aria="{ 'role': 'radiogroup' }"` only when the fieldset contains custom radio controls.
 - **Don't** set `state="error"` without a descriptive `message`.
 
+## 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-flag/accessibility.md

@@ -0,0 +1,39 @@
+# p-flag accessibility integration examples
+
+## Integration examples
+
+### Informative flag without accessible name
+
+#### ❌ Anti-pattern
+
+```tsx
+<PFlag name="germany"></PFlag>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PFlag name="germany" aria={{'aria-label': 'Germany'}}></PFlag>
+```
+
+### Decorative flag with redundant label
+
+#### ❌ Anti-pattern
+
+```tsx
+<PFlag name="germany" aria={{'aria-label': 'Germany'}}></PFlag>
+
+<PText>
+  Germany
+</PText>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PFlag name="germany" ariaHidden={true}></PFlag>
+
+<PText>
+  Germany
+</PText>
+```

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

@@ -42,6 +42,10 @@ The following guidelines provide instructions for designers and developers on th
 - **Do** hide decorative flags from assistive technologies when adjacent text already names the country or region.
 - **Don't** leave informative flags without an accessible name.
 
+## Integration examples
+
+See [accessibility integration examples](./accessibility.md) for paired anti-pattern and recommended implementations.
+
 ## API
 
 ### Properties