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

package/skills/pds-knowledge-react/references/components/p-input-number/examples/Slots.tsx

@@ -0,0 +1,41 @@
+import React from 'react';
+import { PButtonPure, PIcon, PInputNumber, PPopover } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PInputNumber state="error">
+        <span slot="label">
+          Some label with a 
+          <a href="https://designsystem.porsche.com" className="underline">
+            link
+          </a>
+           and a "label-after" slot.
+        </span>
+        <PPopover slot="label-after">
+          Some Popover content with a 
+          <a href="https://designsystem.porsche.com" className="underline">
+            link
+          </a>
+          .
+        </PPopover>
+        <span slot="description">
+          Some description with a 
+          <a href="https://designsystem.porsche.com" className="underline">
+            link
+          </a>
+          .
+        </span>
+        <PIcon slot="start" name="shopping-cart" color="contrast-medium" aria-hidden={true}></PIcon>
+        <PButtonPure slot="end" icon="delete" hideLabel={true} className="p-(--ref-p-input-slotted-padding) m-(--ref-p-input-slotted-margin)" aria={{'aria-label': 'Delete'}}></PButtonPure>
+        <span slot="message">
+          Some error message with a 
+          <a href="https://designsystem.porsche.com" className="underline">
+            link
+          </a>
+          .
+        </span>
+      </PInputNumber>
+    </>
+  )
+}

package/skills/pds-knowledge-react/references/components/p-input-number/p-input-number.md

@@ -0,0 +1,154 @@
+# p-input-number
+
+The `p-input-number` component provides a versatile, user‑friendly interface for entering numeric values. It supports direct keyboard input and increment/decrement controls for precise adjustments. It has a `start` and `end` slot in order to support flexible slotted content.
+
+A `label` is a caption which informs the user what information a particular form field is asking for. The `p-input-number` component can be used with or without a label, but it's recommended to keep the label visible for better accessibility whenever possible. When used without a label, it's mandatory to provide a descriptive label text for screen readers.
+
+While a `placeholder` is optional but recommended to be set whenever bits of example content or hints shall be shown to give the user visual cues to fill out the form.
+
+> **Input Event Handling**
+>
+> React's `onChange` behaves like the native `onInput` (fires on every keystroke). However, our web components follow standard browser behavior, where `onChange` only fires when the input loses focus. To get real-time updates on each keystroke, use `onInput` instead.
+
+## Usage
+
+`p-input-number` is intended for true numeric input scenarios, especially when increment and decrement controls enhance the user experience. It should not be used for values that merely happen to consist of digits — such as postal codes or credit card numbers. For those cases, consider using another input with an appropriate input mode. For further guidance, see the [MDN documentation on number inputs](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/number#using_number_inputs).
+
+### Do:
+
+- Use when a numeric value is required or optional.
+- Use without a label only when the context is clear.
+- Use for validation and error of input.
+- Use asterisk for required fields.
+
+### Don't:
+
+- Don't use labels with more than two words whenever possible (keep it short and descriptive).
+- Don't use instructional or description text for the label.
+
+---
+
+## Related Components
+
+- [Input Date](../p-input-date/p-input-date.md)
+- [Input Email](../p-input-email/p-input-email.md)
+- [Input Month](../p-input-month/p-input-month.md)
+- [Input Password](../p-input-password/p-input-password.md)
+- [Input Search](../p-input-search/p-input-search.md)
+- [Input Tel](../p-input-tel/p-input-tel.md)
+- [Input Text](../p-input-text/p-input-text.md)
+- [Input Time](../p-input-time/p-input-time.md)
+- [Input Url](../p-input-url/p-input-url.md)
+- [Input Week](../p-input-week/p-input-week.md)
+
+## Accessibility support
+
+### Keyboard
+
+| Key / state | Function |
+| --- | --- |
+| `Tab`, `Shift-Tab` | Moves focus to the next (or previous) focusable element. |
+| `Arrow Up/Down` | Sets increments/decrements in regards of the steps |
+
+### ARIA enhancements
+
+#### Internal **ARIA** that is managed by the component:
+
+| ARIA | Usage |
+| --- | --- |
+| `aria-describedby="IDREF"` | Defines the accessible description combined with the status message. |
+| `role="status"`, `role="alert"` | When `message` and `state` or `loading` prop change, the status message is announced. |
+| `aria-hidden="true"` | If `required` attribute is set, the visible asterisk indicator is hidden from assistive technologies. |
+| `aria-invalid="true"` | If `error` state is set. |
+| `aria-live="polite"` | If the `maxlength` attribute is present, the counter is announced via ARIA live region. |
+
+## Development considerations
+
+### Exposing the `unit` prop
+
+The `unit` prop is not exposed to assistive technologies by default. If you provide a `unit` abbreviation, you need to dissolve it in real text through the `description` prop. For example, if you use `kmh`, you can set the `description` prop to `kilometers per hour`. This way, the screen reader will read out the full text.
+
+### Disabled state
+
+In general, avoid using the `disabled` state. Disabled elements are no longer focusable and may be missed by screen reader users. They can also confuse sighted users if the reason they are disabled is not made clear.
+
+### Common do's and don'ts
+
+- **Do** keep a persistent label and spell out unit abbreviations in the `description` prop.
+- **Do** use the component state/message API so validation and status changes are announced.
+- **Do** use clear error wording that helps users recover.
+- **Don't** rely on placeholder text or the `unit` prop alone for accessible context.
+- **Don't** use `hide-label` without an accessible name.
+
+## Limitations
+
+Due to the nature of **Web Components** and **shadow DOM**, there are limitations when using some **ARIA** attributes to define relationships between elements across different shadow DOMs or shadow DOM/light DOM combinations.
+
+| ARIA | Support |
+| --- | --- |
+| `aria-labelledby` | 🚫 |
+| `aria-describedby` | 🚫 |
+
+## Integration examples
+
+See [accessibility integration examples](./accessibility.md) for paired anti-pattern and recommended implementations.
+
+## API
+
+### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `autoComplete` | `string` | `undefined` | Provides the browser with a data type hint to enable relevant autofill suggestions (e.g. `autocomplete='postal-code'`). |
+| `compact` | `boolean` | `false` | Reduces the input height and padding for a more compact layout. |
+| `controls` | `boolean` | `false` | Shows increment/decrement spin buttons inside the field to adjust the numeric value by clicking. |
+| `description` | `string` | `''` | Sets a supplementary description displayed below the label to provide additional context. |
+| `disabled` | `boolean` | `false` | Disables the field, preventing all input. The value is not submitted with the form. |
+| `form` | `string` | `undefined` | Associates the field with a form element by its ID when the field is not nested directly inside it. |
+| `hideLabel` | `boolean`<br>`BreakpointCustomizable<boolean>` | `false` | Hides the visible label while keeping it accessible to screen readers. Supports responsive breakpoint values. |
+| `label` | `string` | `''` | Sets the visible label text displayed above the input field. |
+| `loading` _(experimental)_ | `boolean` | `false` | @experimental Disables the field and displays a loading spinner to indicate an ongoing operation. |
+| `max` | `number` | `undefined` | Sets the maximum allowed numeric value. Values above this are invalid. |
+| `message` | `string` | `''` | Sets the validation feedback message displayed below the field when `state` is `success` or `error`. |
+| `min` | `number` | `undefined` | Sets the minimum allowed numeric value. Values below this are invalid. |
+| `name` _(required)_ | `string` | `undefined` | Sets the name submitted with the form data to identify this field's value on the server. |
+| `placeholder` | `string` | `''` | Sets placeholder text shown inside the field when it is empty, to hint at the expected format. |
+| `readOnly` | `boolean` | `false` | Makes the field read-only — the value is displayed but cannot be edited. The value is still submitted with the form. |
+| `required` | `boolean` | `false` | Marks the field as required — form submission is blocked while this field is empty. |
+| `state` | `'none'` `'error'` `'success'` | `'none'` | Sets the validation state, controlling the visual appearance and style of the feedback message (`none`, `success`, `error`). |
+| `step` | `number` | `1` | Sets the stepping granularity — the value must be a multiple of this number. Also controls step button increment size. |
+| `value` | `string | number | null` | `''` | Sets the current numeric value of the field. |
+
+### Events
+
+| Event | Type | Description |
+| --- | --- | --- |
+| `blur` | `CustomEvent<InputNumberBlurEventDetail>`<br>`Event` | Emitted when the number input has lost focus. |
+| `change` | `CustomEvent<InputNumberChangeEventDetail>`<br>`Event` | Emitted when the number input loses focus after its value was changed. |
+| `input` | `CustomEvent<InputNumberInputEventDetail>`<br>`InputEvent` | Emitted when the value has been changed as a direct result of a user action. |
+
+### Slots
+
+| Slot | Required | Allowed tag names | Description |
+| --- | --- | --- | --- |
+| `label` | no | — | Shows a label. Only [phrasing content](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Content_categories#Phrasing_content) is allowed. |
+| `label-after` | no | — | Places additional content after the label text (for content that should not be part of the label, e.g. external links or `p-popover`). |
+| `description` | no | — | Shows a description. Only [phrasing content](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Content_categories#Phrasing_content) is allowed. |
+| `message` | no | — | Shows a state message. Only [phrasing content](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Content_categories#Phrasing_content) is allowed. |
+| `start` | no | — | Shows content at the start of the input (e.g. unit prefix). |
+| `end` | no | — | Shows content at the end of the input (e.g. toggle button, unit suffix). |
+
+### CSS Variables
+
+| CSS Variable | Default | Description |
+| --- | --- | --- |
+| `--ref-p-input-slotted-padding` | — | When slotting a `p-button-pure` or `p-link-pure` this variable needs to be set as `padding` in oder to adjust the alignment correctly. |
+| `--ref-p-input-slotted-margin` | — | When slotting a `p-button-pure` or `p-link-pure` this variable needs to be set as `margin` in oder to adjust the spacings correctly. |
+
+## Examples
+
+| Example | When to use | File |
+| --- | --- | --- |
+| Default | Minimal default configuration. | [./examples/Default.tsx](./examples/Default.tsx) |
+| Form | The `p-input-number` can be integrated into a form in two ways: **controlled** or **uncontrolled**, depending on your needs. | [./examples/Form.tsx](./examples/Form.tsx) |
+| Slots | Use named slots when `label`, `description` or `message` need markup such as a link. | [./examples/Slots.tsx](./examples/Slots.tsx) |

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

@@ -0,0 +1,45 @@
+# p-input-password accessibility integration examples
+
+## Integration examples
+
+### Placeholder used as the only label
+
+#### ❌ Anti-pattern
+
+```tsx
+<PInputPassword name="password" placeholder="Password"></PInputPassword>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PInputPassword name="password" label="Password" description="Use at least 8 characters with one number."></PInputPassword>
+```
+
+### Hidden label without accessible name
+
+#### ❌ Anti-pattern
+
+```tsx
+<PInputPassword name="password" hideLabel={true}></PInputPassword>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PInputPassword name="password" hideLabel={true} label="Password"></PInputPassword>
+```
+
+### Validation feedback via state and message API
+
+#### ❌ Anti-pattern
+
+```tsx
+<PInputPassword name="password" label="Password" aria-invalid={true} message="Invalid"></PInputPassword>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PInputPassword name="password" label="Password" state="error" message="Enter a password with at least 8 characters and one number."></PInputPassword>
+```

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

@@ -0,0 +1,10 @@
+import React from 'react';
+import { PInputPassword } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PInputPassword label="Some label" name="some-name" toggle={true}></PInputPassword>
+    </>
+  )
+}

package/skills/pds-knowledge-react/references/components/p-input-password/examples/Form.tsx

@@ -0,0 +1,51 @@
+import React from 'react';
+import {
+  type InputPasswordInputEventDetail,
+  PButton,
+  PInputPassword,
+  type PInputPasswordProps,
+  PText,
+} from '@porsche-design-system/components-react';
+import { FormEvent, useState } from 'react';
+
+export const Example = () => {
+  const [form, setForm] = useState({ myInputPassword: '' });
+  const [lastSubmittedData, setLastSubmittedData] = useState<any>();
+
+  const onInput = (e: CustomEvent<InputPasswordInputEventDetail>) => {
+    const { name, value } = e.target as HTMLElement & PInputPasswordProps;
+    setForm((prev) => ({
+      ...prev,
+      [name]: value,
+    }));
+  };
+
+  const onSubmit = (e: FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    setLastSubmittedData(JSON.stringify(form));
+  };
+
+  const onReset = (e: FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    setForm({ myInputPassword: '' });
+  };
+
+  return (
+    <>
+      <form onSubmit={onSubmit} onReset={onReset} className="flex flex-col gap-fluid-sm">
+        <PInputPassword
+          name="myInputPassword"
+          label="Some Label"
+          toggle={true}
+          value={form.myInputPassword}
+          onInput={onInput}
+        />
+        <div className="flex gap-fluid-sm">
+          <PButton type="submit">Submit</PButton>
+          <PButton type="reset">Reset</PButton>
+        </div>
+        <PText>Last submitted data: {lastSubmittedData}</PText>
+      </form>
+    </>
+  );
+};

package/skills/pds-knowledge-react/references/components/p-input-password/examples/Slots.tsx

@@ -0,0 +1,39 @@
+import React from 'react';
+import { PInputPassword, PPopover } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PInputPassword state="error">
+        <span slot="label">
+          Some label with a 
+          <a href="https://designsystem.porsche.com" className="underline">
+            link
+          </a>
+           and a "label-after" slot.
+        </span>
+        <PPopover slot="label-after">
+          Some Popover content with a 
+          <a href="https://designsystem.porsche.com" className="underline">
+            link
+          </a>
+          .
+        </PPopover>
+        <span slot="description">
+          Some description with a 
+          <a href="https://designsystem.porsche.com" className="underline">
+            link
+          </a>
+          .
+        </span>
+        <span slot="message">
+          Some error message with a 
+          <a href="https://designsystem.porsche.com" className="underline">
+            link
+          </a>
+          .
+        </span>
+      </PInputPassword>
+    </>
+  )
+}

package/skills/pds-knowledge-react/references/components/p-input-password/examples/Toggle.tsx

@@ -0,0 +1,10 @@
+import React from 'react';
+import { PInputPassword } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PInputPassword label="Some label" name="some-name" toggle={true}></PInputPassword>
+    </>
+  )
+}

package/skills/pds-knowledge-react/references/components/p-input-password/p-input-password.md

@@ -0,0 +1,149 @@
+# p-input-password
+
+The `p-input-password` component enables secure password entry by obscuring the typed characters. Displayed as a one-line plain text editor, it ensures the password remains hidden to protect user privacy. Additionally, the component includes a toggle button that allows users to reveal the password in clear text when needed, offering both security and convenience.
+
+A `label` is a caption which informs the user what information a particular form field is asking for. The `p-input-password` component can be used with or without a label, but it's recommended to keep the label visible for better accessibility whenever possible. When used without a label, it's mandatory to provide a descriptive label text for screen readers.
+
+While a `placeholder` is optional but recommended to be set whenever bits of example content or hints shall be shown to give the user visual cues to fill out the form.
+
+> **Input Event Handling**
+>
+> React's `onChange` behaves like the native `onInput` (fires on every keystroke). However, our web components follow standard browser behavior, where `onChange` only fires when the input loses focus. To get real-time updates on each keystroke, use `onInput` instead.
+
+## Usage
+
+### Do:
+
+- Use when a text input of the user is required or optional.
+- Use for password input.
+- Use without a label only when the context is clear.
+- Use for validation and error of input.
+- Use asterisk for required fields.
+
+### Don't:
+
+- Don't use labels with more than two words whenever possible (keep it short and descriptive).
+- Don't use instructional or description text for the label.
+
+---
+
+## Related Components
+
+- [Input Date](../p-input-date/p-input-date.md)
+- [Input Email](../p-input-email/p-input-email.md)
+- [Input Month](../p-input-month/p-input-month.md)
+- [Input Number](../p-input-number/p-input-number.md)
+- [Input Search](../p-input-search/p-input-search.md)
+- [Input Tel](../p-input-tel/p-input-tel.md)
+- [Input Text](../p-input-text/p-input-text.md)
+- [Input Time](../p-input-time/p-input-time.md)
+- [Input Url](../p-input-url/p-input-url.md)
+- [Input Week](../p-input-week/p-input-week.md)
+
+## Accessibility support
+
+### Keyboard
+
+| Key / state | Function |
+| --- | --- |
+| `Tab`, `Shift-Tab` | Moves focus to the next (or previous) focusable element. |
+
+### ARIA enhancements
+
+#### Internal **ARIA** that is managed by the component:
+
+| ARIA | Usage |
+| --- | --- |
+| `aria-label="STRING"` | Defines the accessible name combined with the description and status message. |
+| `role="status"`, `role="alert"` | When `message` and `state` or `loading` prop change, the status message is announced. |
+| `aria-hidden="true"` | If `required` attribute is set, the visible asterisk indicator is hidden from assistive technologies. |
+| `aria-invalid="true"` | If `error` state is set. |
+| `aria-live="polite"` | If the `maxlength` attribute is present, the counter is announced via ARIA live region. |
+| `aria-pressed="BOOLEAN"` | Defines the state of the visibility for the toggle button. |
+
+## Development considerations
+
+### Disabled state
+
+In general, avoid using the `disabled` state. Disabled elements are no longer focusable and may be missed by screen reader users. They can also confuse sighted users if the reason they are disabled is not made clear.
+
+### Common do's and don'ts
+
+- **Do** keep a persistent label and use helper/description text when additional context is required.
+- **Do** use the component state/message API so validation and status changes are announced.
+- **Do** use clear error wording that helps users recover.
+- **Don't** rely on placeholder text as the only label.
+- **Don't** use `hide-label` without an accessible name.
+
+## Limitations
+
+Due to the nature of **Web Components** and **shadow DOM**, there are limitations when using some **ARIA** attributes to define relationships between elements across different shadow DOMs or shadow DOM/light DOM combinations.
+
+| ARIA | Support |
+| --- | --- |
+| `aria-labelledby` | 🚫 |
+| `aria-describedby` | 🚫 |
+
+## Integration examples
+
+See [accessibility integration examples](./accessibility.md) for paired anti-pattern and recommended implementations.
+
+## API
+
+### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `autoComplete` | `string` | `undefined` | Provides the browser with a password autofill hint (e.g. `autocomplete='current-password'` or `autocomplete='new-password'`). |
+| `compact` | `boolean` | `false` | Reduces the input height and padding for a more compact layout. |
+| `description` | `string` | `''` | Sets a supplementary description displayed below the label to provide additional context. |
+| `disabled` | `boolean` | `false` | Disables the field, preventing all input. The value is not submitted with the form. |
+| `form` | `string` | `undefined` | Associates the field with a form element by its ID when the field is not nested directly inside it. |
+| `hideLabel` | `boolean`<br>`BreakpointCustomizable<boolean>` | `false` | Hides the visible label while keeping it accessible to screen readers. Supports responsive breakpoint values. |
+| `label` | `string` | `''` | Sets the visible label text displayed above the input field. |
+| `loading` _(experimental)_ | `boolean` | `false` | @experimental Disables the field and displays a loading spinner to indicate an ongoing operation. |
+| `maxLength` | `number` | `undefined` | Sets the maximum number of characters the user can enter. |
+| `message` | `string` | `''` | Sets the validation feedback message displayed below the field when `state` is `success` or `error`. |
+| `minLength` | `number` | `undefined` | Sets the minimum number of characters required for the field to be considered valid. |
+| `name` _(required)_ | `string` | `undefined` | Sets the name submitted with the form data to identify this field's value on the server. |
+| `placeholder` | `string` | `''` | Sets placeholder text shown inside the field when it is empty. |
+| `readOnly` | `boolean` | `false` | Makes the field read-only — the value is displayed but cannot be edited. The value is still submitted with the form. |
+| `required` | `boolean` | `false` | Marks the field as required — form submission is blocked while this field is empty. |
+| `state` | `'none'` `'error'` `'success'` | `'none'` | Sets the validation state, controlling the visual appearance and style of the feedback message (`none`, `success`, `error`). |
+| `toggle` | `boolean` | `false` | Shows a toggle button that switches the password between masked and plain text visibility. |
+| `value` | `string | null` | `''` | Sets the current password value of the field. |
+
+### Events
+
+| Event | Type | Description |
+| --- | --- | --- |
+| `blur` | `CustomEvent<InputPasswordBlurEventDetail>`<br>`Event` | Emitted when the password input has lost focus. |
+| `change` | `CustomEvent<InputPasswordChangeEventDetail>`<br>`Event` | Emitted when the password input loses focus after its value was changed. |
+| `input` | `CustomEvent<InputPasswordInputEventDetail>`<br>`InputEvent` | Emitted when the value has been changed as a direct result of a user action. |
+
+### Slots
+
+| Slot | Required | Allowed tag names | Description |
+| --- | --- | --- | --- |
+| `label` | no | — | Shows a label. Only [phrasing content](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Content_categories#Phrasing_content) is allowed. |
+| `label-after` | no | — | Places additional content after the label text (for content that should not be part of the label, e.g. external links or `p-popover`). |
+| `description` | no | — | Shows a description. Only [phrasing content](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Content_categories#Phrasing_content) is allowed. |
+| `message` | no | — | Shows a state message. Only [phrasing content](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Content_categories#Phrasing_content) is allowed. |
+| `start` | no | — | Shows content at the start of the input (e.g. unit prefix). |
+| `end` | no | — | Shows content at the end of the input (e.g. toggle button, unit suffix). |
+
+### CSS Variables
+
+| CSS Variable | Default | Description |
+| --- | --- | --- |
+| `--ref-p-input-slotted-padding` | — | When slotting a `p-button-pure` or `p-link-pure` this variable needs to be set as `padding` in oder to adjust the alignment correctly. |
+| `--ref-p-input-slotted-margin` | — | When slotting a `p-button-pure` or `p-link-pure` this variable needs to be set as `margin` in oder to adjust the spacings correctly. |
+
+## Examples
+
+| Example | When to use | File |
+| --- | --- | --- |
+| Default | Minimal default configuration. | [./examples/Default.tsx](./examples/Default.tsx) |
+| Form | The `p-input-password` can be integrated into a form in two ways: **controlled** or **uncontrolled**, depending on your needs. | [./examples/Form.tsx](./examples/Form.tsx) |
+| Show password toggle button | If you want to show the password toggle button, you can pass `toggle="true"`. | [./examples/Toggle.tsx](./examples/Toggle.tsx) |
+| Slots | Use named slots when `label`, `description` or `message` need markup such as a link. | [./examples/Slots.tsx](./examples/Slots.tsx) |

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

@@ -0,0 +1,59 @@
+# p-input-search accessibility integration examples
+
+## Integration examples
+
+### Placeholder used as the only label
+
+#### ❌ Anti-pattern
+
+```tsx
+<PInputSearch name="search" placeholder="Search"></PInputSearch>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PInputSearch name="search" label="Search vehicles" description="Search by model name or VIN."></PInputSearch>
+```
+
+### ARIA on component host vs aria prop
+
+#### ❌ Anti-pattern
+
+```tsx
+<PInputSearch name="search" label="Search vehicles" role="combobox" aria-expanded={false} aria-haspopup="listbox"></PInputSearch>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PInputSearch name="search" label="Search vehicles" aria={{'role': 'combobox', 'aria-expanded': 'false', 'aria-haspopup': 'listbox'}}></PInputSearch>
+```
+
+### Hidden label without accessible name
+
+#### ❌ Anti-pattern
+
+```tsx
+<PInputSearch name="search" hideLabel={true}></PInputSearch>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PInputSearch name="search" hideLabel={true} label="Search vehicles"></PInputSearch>
+```
+
+### Validation feedback via state and message API
+
+#### ❌ Anti-pattern
+
+```tsx
+<PInputSearch name="search" label="Search vehicles" aria-invalid={true} message="Invalid"></PInputSearch>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PInputSearch name="search" label="Search vehicles" state="error" message="Enter at least 3 characters to search."></PInputSearch>
+```

package/skills/pds-knowledge-react/references/components/p-input-search/examples/AriaCombobox.tsx

@@ -0,0 +1,35 @@
+import React from 'react';
+import { PIcon, PInputSearch } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <div className="flex w-full max-w-md flex-col gap-static-xs self-start [&>p-input-search]:min-w-0">
+        <PInputSearch label="Search" name="aria-sketch" indicator={true} clear={true} aria={{'role': 'combobox', 'aria-expanded': 'true', 'aria-haspopup': 'listbox', 'aria-autocomplete': 'list', 'aria-controls': 'listbox'}}></PInputSearch>
+        <div id="listbox" role="listbox" tabIndex={0} aria-label="Search options" className="max-h-48 p-static-sm overflow-y-auto rounded-xl border-thin border-contrast-lower bg-background-base shadow-md ">
+          <div role="option" aria-selected="false" className="px-static-sm py-static-sm cursor-pointer bg-background-base hover:bg-frosted transition-colors duration-300 rounded-sm">
+            718
+          </div>
+          <div role="option" aria-selected="false" className="px-static-sm py-static-sm cursor-pointer bg-background-base hover:bg-frosted transition-colors duration-300 rounded-sm">
+            911
+          </div>
+          <div role="option" aria-selected="true" className="flex px-static-sm py-static-sm cursor-pointer bg-background-base hover:bg-frosted transition-colors duration-300 rounded-sm">
+            <span>
+              Cayenne
+            </span>
+            <PIcon name="check" color="primary" aria-hidden={true} className="ms-auto"></PIcon>
+          </div>
+          <div role="option" aria-selected="false" className="px-static-sm py-static-sm cursor-pointer bg-background-base hover:bg-frosted transition-colors duration-300 rounded-sm">
+            Macan
+          </div>
+          <div role="option" aria-selected="false" className="px-static-sm py-static-sm cursor-pointer bg-background-base hover:bg-frosted transition-colors duration-300 rounded-sm">
+            Panamera
+          </div>
+          <div role="option" aria-selected="false" className="px-static-sm py-static-sm cursor-pointer bg-background-base hover:bg-frosted transition-colors duration-300 rounded-sm">
+            Taycan
+          </div>
+        </div>
+      </div>
+    </>
+  )
+}

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

@@ -0,0 +1,10 @@
+import React from 'react';
+import { PInputSearch } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PInputSearch label="Some label" name="Some name" clear={true} indicator={true}></PInputSearch>
+    </>
+  )
+}