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

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

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

package/{skill → skills/pds-knowledge-react}/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-react/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
+
+```tsx
+<PSelect name="model">
+  <PSelectOption value="">
+    Select a model
+  </PSelectOption>
+  <PSelectOption value="carrera">
+    911 Carrera
+  </PSelectOption>
+  <PSelectOption value="carrera-s">
+    911 Carrera S
+  </PSelectOption>
+</PSelect>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PSelect label="Porsche model" name="model" description="Choose the model for your configuration.">
+  <PSelectOption value="carrera">
+    911 Carrera
+  </PSelectOption>
+  <PSelectOption value="carrera-s">
+    911 Carrera S
+  </PSelectOption>
+</PSelect>
+```
+
+### Ambiguous option labels without field context
+
+#### ❌ Anti-pattern
+
+```tsx
+<PSelect label="Model" name="model">
+  <PSelectOption value="base">
+    Base
+  </PSelectOption>
+  <PSelectOption value="s">
+    S
+  </PSelectOption>
+</PSelect>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PSelect label="Porsche 911 trim" name="model" description="Select the trim level for your configuration.">
+  <PSelectOption value="carrera">
+    911 Carrera
+  </PSelectOption>
+  <PSelectOption value="carrera-s">
+    911 Carrera S
+  </PSelectOption>
+</PSelect>
+```
+
+### Hidden label without accessible name
+
+#### ❌ Anti-pattern
+
+```tsx
+<PSelect name="model" hideLabel={true}>
+  <PSelectOption value="carrera">
+    911 Carrera
+  </PSelectOption>
+</PSelect>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PSelect label="Porsche model" name="model" hideLabel={true}>
+  <PSelectOption value="carrera">
+    911 Carrera
+  </PSelectOption>
+</PSelect>
+```
+
+### Validation feedback via state and message API
+
+#### ❌ Anti-pattern
+
+```tsx
+<PSelect label="Porsche model" name="model" aria-invalid={true} message="Required">
+  <PSelectOption value="carrera">
+    911 Carrera
+  </PSelectOption>
+  <PSelectOption value="carrera-s">
+    911 Carrera S
+  </PSelectOption>
+</PSelect>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PSelect label="Porsche model" name="model" state="error" message="Select a model to continue with your configuration.">
+  <PSelectOption value="carrera">
+    911 Carrera
+  </PSelectOption>
+  <PSelectOption value="carrera-s">
+    911 Carrera S
+  </PSelectOption>
+</PSelect>
+```
+
+### Error state without recovery guidance
+
+#### ❌ Anti-pattern
+
+```tsx
+<PSelect label="Porsche model" name="model" state="error" message="Invalid">
+  <PSelectOption value="carrera">
+    911 Carrera
+  </PSelectOption>
+  <PSelectOption value="carrera-s">
+    911 Carrera S
+  </PSelectOption>
+</PSelect>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PSelect label="Porsche model" name="model" required={true} state="error" message="Select a Porsche model. This field is required to continue.">
+  <PSelectOption value="carrera">
+    911 Carrera
+  </PSelectOption>
+  <PSelectOption value="carrera-s">
+    911 Carrera S
+  </PSelectOption>
+</PSelect>
+```

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

@@ -9,7 +9,7 @@ import {
   type SelectChangeEventDetail,
   type SelectToggleEventDetail,
 } from '@porsche-design-system/components-react';
-import { useCallback, useRef, useState } from 'react';
+import { useCallback, useMemo, useRef, useState } from 'react';
 
 const useDebounce = <T,>(callback: (value: T) => void, delay = 400) => {
   const timer = useRef<number | undefined>(undefined);
@@ -19,6 +19,20 @@ const useDebounce = <T,>(callback: (value: T) => void, delay = 400) => {
   };
 };
 
+const getFilterStatusMessage = (
+  searchValue: string,
+  optionCount: number,
+  isLoading: boolean,
+  error: string | null
+): string => {
+  if (error) return '';
+  if (isLoading) return 'Loading options';
+  const term = searchValue.trim();
+  if (!term) return '';
+  if (optionCount === 0) return 'No results found';
+  return optionCount === 1 ? '1 result available' : `${optionCount} results available`;
+};
+
 export const Example = () => {
   const [value, setValue] = useState<PSelectProps['value']>(undefined);
   const [options, setOptions] = useState<{ value: string; label: string }[]>([]);
@@ -83,6 +97,11 @@ export const Example = () => {
     }
   };
 
+  const filterStatusMessage = useMemo(
+    () => getFilterStatusMessage(searchValue, options.length, initialLoading || loading, error),
+    [searchValue, options.length, initialLoading, loading, error]
+  );
+
   return (
     <PSelect name="async-search-select" label="Async Search" value={value} onChange={onChange} onToggle={onToggle}>
       <PInputSearch
@@ -100,6 +119,11 @@ export const Example = () => {
         onChange={(e: any) => e.stopPropagation()}
       />
 
+      {/* Persistent status announcer for assistive technologies (keep always in the DOM) */}
+      <div slot="options-status" className="sr-only" aria-live="polite" aria-atomic="true">
+        {filterStatusMessage}
+      </div>
+
       {/* Initial skeleton loading */}
       {initialLoading &&
         !error &&
@@ -112,15 +136,14 @@ export const Example = () => {
         </PSelectOption>
       ))}
 
-      {/* No filter results */}
-      {!initialLoading && options.length === 0 && !error && (
+      {/* No filter results (visual only; announcements come from the live region) */}
+      {!initialLoading && !loading && options.length === 0 && !error && (
         <div
           slot="options-status"
           className="text-contrast-medium cursor-not-allowed py-static-sm px-[12px]"
-          role="alert"
+          aria-hidden="true"
         >
-          <span aria-hidden="true">–</span>
-          <span className="sr-only">No results found</span>
+          –
         </div>
       )}
 

package/{skill → skills/pds-knowledge-react}/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
 

package/skills/pds-knowledge-react/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
+
+```tsx
+<PButton aria-haspopup="dialog">
+  Filter results
+</PButton>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PButton aria={{'aria-haspopup': 'dialog'}}>
+  Filter results
+</PButton>
+```
+
+### Dialog label on component host vs header slot
+
+#### ❌ Anti-pattern
+
+```tsx
+<PSheet aria-label="Filters">
+  ...
+</PSheet>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PSheet>
+  <PHeading slot="header" tag="h2" size="lg">
+    Filter results
+  </PHeading>
+  ...
+</PSheet>
+
+{/* or with aria prop when no visible header is shown */}
+
+<PSheet aria={{'aria-label': 'Filter results'}}>
+  ...
+</PSheet>
+```
+
+### Sheet trigger without popup semantics
+
+#### ❌ Anti-pattern
+
+```tsx
+<PButton>
+  Open
+</PButton>
+
+<PSheet>
+  <PHeading slot="header" tag="h2" size="lg">
+    Filters
+  </PHeading>
+  ...
+</PSheet>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PButton aria={{'aria-haspopup': 'dialog'}}>
+  Filter results
+</PButton>
+
+<PSheet>
+  <PHeading slot="header" tag="h2" size="lg">
+    Filter results
+  </PHeading>
+  ...
+</PSheet>
+```

package/{skill → skills/pds-knowledge-react}/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-react/references/components/p-spinner/accessibility.md

@@ -0,0 +1,31 @@
+# p-spinner accessibility integration examples
+
+## Integration examples
+
+### Spinner mounted only when loading starts
+
+#### ❌ Anti-pattern
+
+```tsx
+{isLoading && <PSpinner />}
+```
+
+#### ✅ Recommended
+
+```tsx
+<PSpinner aria={{'aria-label': 'Loading vehicle configuration'}}></PSpinner>
+```
+
+### Spinner without loading message
+
+#### ❌ Anti-pattern
+
+```tsx
+<PSpinner></PSpinner>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PSpinner aria={{'aria-label': 'Loading vehicle configuration'}}></PSpinner>
+```

package/{skill → skills/pds-knowledge-react}/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-react/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
+
+```tsx
+<PStepperHorizontal>
+  <PStepperHorizontalItem state="complete">
+    Step 1
+  </PStepperHorizontalItem>
+  <PStepperHorizontalItem state="current">
+    Step 2
+  </PStepperHorizontalItem>
+</PStepperHorizontal>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PStepperHorizontal>
+  <PStepperHorizontalItem state="complete">
+    Configure vehicle
+  </PStepperHorizontalItem>
+  <PStepperHorizontalItem state="current">
+    Choose delivery date
+  </PStepperHorizontalItem>
+  <PStepperHorizontalItem>
+    Review and confirm
+  </PStepperHorizontalItem>
+</PStepperHorizontal>
+```

package/{skill → skills/pds-knowledge-react}/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-react/references/components/p-switch/accessibility.md

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

package/{skill → skills/pds-knowledge-react}/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-react/references/components/p-table/accessibility.md

@@ -0,0 +1,47 @@
+# p-table accessibility integration examples
+
+## Integration examples
+
+### Data table without caption
+
+#### ❌ Anti-pattern
+
+```tsx
+<PTable>
+  <PTableHead>
+    ...
+  </PTableHead>
+  <PTableBody>
+    ...
+  </PTableBody>
+</PTable>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PTable caption="Available Porsche 911 models and starting prices">
+  <PTableHead>
+    ...
+  </PTableHead>
+  <PTableBody>
+    ...
+  </PTableBody>
+</PTable>
+```
+
+### Column with hidden label
+
+#### ❌ Anti-pattern
+
+```tsx
+<PTableHeadCell hideLabel={true}></PTableHeadCell>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PTableHeadCell hideLabel={true}>
+  Model
+</PTableHeadCell>
+```

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

@@ -30,21 +30,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',
+  },
 ];
 
 export const Example = () => {
@@ -56,7 +56,8 @@ export const Example = () => {
     setHead((prev) => prev.map((item) => ({ ...item, active: false, ...(item.id === id && e.detail) })));
     setData((prev) =>
       [...prev].sort((a, b) => {
-        return direction === 'asc' ? a[id].localeCompare(b[id]) : b[id].localeCompare(a[id]);
+        const result = String(a[id]).localeCompare(String(b[id]), undefined, { numeric: true });
+        return direction === 'asc' ? result : -result;
       })
     );
   }, []);

package/{skill → skills/pds-knowledge-react}/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.tsx](./examples/CaptionProperty.tsx) |
 | Caption via Slot | Instead of using the the property, the table's caption can be provided via the `caption` slot. | [./examples/CaptionSlot.tsx](./examples/CaptionSlot.tsx) |
 | 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.tsx](./examples/LayoutFixed.tsx) |
-| Sortable Columns | The `p-table`'s column headers can be configured by setting properties on each `p-table-head-cell`. | [./examples/Sorting.tsx](./examples/Sorting.tsx) |
+| 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.tsx](./examples/Sorting.tsx) |
 | 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.tsx](./examples/HideLabel.tsx) |
 | Advanced Table | The appearance of a table's contents can be customized as illustrated in the following example. | [./examples/Advanced.tsx](./examples/Advanced.tsx) |