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

package/skill/references/components/p-popover/p-popover.md

@@ -0,0 +1,116 @@
+# p-popover
+
+The `p-popover` component displays additional contextual content in an overlay and should be used when users need optional details without leaving their current context. It is triggered by a button and renders its own info button by default, or you can provide a custom trigger via the `button` slot.
+
+By default, the Popover works **uncontrolled**: it manages its own visibility and toggles open or closed when its info button (or a slotted trigger) is clicked. It is dismissed on outside click, on `Escape`, or when keyboard focus leaves the Popover.
+
+Alternatively, the Popover can be used in a **controlled** mode by setting the `open` prop together with a slotted `button` (the default info button does not toggle in this mode). In this mode you own the open state: the Popover only emits the `dismiss` event when the user requests to close it (via `Escape`, an outside click or when keyboard focus leaves the Popover), and you decide whether to update `open` in response.
+
+**Hint:** The `p-popover` utilizes the [Popover API](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) and gets rendered on the `#top-layer` which enables it to be shown correctly even when used e.g. within a scroll container.
+
+## Usage
+
+### Do:
+
+- Use it to display additional information that is not necessary for task completion or to provide further explanation about a workflow.
+- Position popovers in a way that they do not block related content.
+- Choose a preferred direction in which the popover should open, or it will automatically open in the direction with the most available space.
+- Use it consistently throughout your site.
+
+### Don't:
+
+- Don't use for content that can be displayed directly.
+
+---
+
+## References
+
+Nielsen Norman Group [Tooltip Guidelines](https://nngroup.com/articles/tooltip-guidelines)
+
+## Accessibility support
+
+### Keyboard
+
+| Key / state | Function |
+| --- | --- |
+| `Tab`, `Shift-Tab` | Moves focus to the next (or previous) focusable element. |
+| `Enter`, `Space` | - Opens/closes the popover. |
+
+### ARIA enhancements
+
+#### External **ARIA** provided by the `aria` property:
+
+| ARIA | Usage |
+| --- | --- |
+| `aria-label` | Defines a string value that labels the interactive element. |
+
+#### Internal **ARIA** that is managed by the component:
+
+| ARIA | Usage |
+| --- | --- |
+| `aria-expanded="BOOLEAN"` | Indicates that the popover element is displayed/hidden. |
+| `aria-details="IDREF"` | References the element that provides additional information about the popover. |
+
+## Development considerations
+
+In **uncontrolled** mode the `p-popover` component does not manage `aria-expanded` on a custom slotted button, because it does not expose its internal `open` state publicly. In this case the default info button (which the component fully controls) already exposes `aria-expanded` for you.
+
+In **controlled** mode the consumer owns the `open` state, so the slotted trigger *can* (and should) expose `aria-expanded` to match the default button's semantics. Bind it to your `open` state via the trigger's `aria` property, e.g. `aria={{ 'aria-expanded': open ? 'true' : 'false' }}`, so it stays in sync as the popover opens and closes.
+
+### Common do's and don'ts
+
+- **Do** prefer the built-in popover trigger when possible so `aria-expanded` is managed internally.
+- **Do** provide an accessible name on a custom slotted button when you cannot use the default trigger.
+- **Do** pass additional ARIA via the `aria` prop when the default labeling is not sufficient.
+- **Don't** use an unnamed custom slotted trigger button.
+- **Don't** add native `aria-*` attributes directly on the component host.
+
+## API
+
+### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `aria` | `PopoverAriaAttribute` | `undefined` | Sets ARIA attributes on the popover panel to improve accessibility for screen readers. |
+| `compact` | `boolean` | `undefined` | Reduces padding and spacing for a more compact layout, useful in space-constrained interfaces. |
+| `description` | `string` | `undefined` | Sets the text content displayed inside the popover panel when it is open, providing contextual help or information. Takes precedence over the default slot when both are provided. |
+| `direction` | `'top'` `'right'` `'bottom'` `'left'` | `'bottom'` | Sets the preferred direction for the popover to open relative to its trigger button. Falls back to the direction with the most available viewport space. |
+| `open` | `boolean` | `undefined` | Controls whether the popover is visible. When set (controlled mode), visibility follows this prop and the consumer owns the open state via a slotted `button`. When omitted (uncontrolled mode), the component manages visibility itself. |
+
+### Events
+
+| Event | Type | Description |
+| --- | --- | --- |
+| `dismiss` | `CustomEvent<void>` | Emitted in controlled mode when the user requests to close the popover via the Escape key, an outside click, or when keyboard focus leaves the popover (Tab / Shift+Tab). |
+
+### Controlled properties
+
+- `open` — a controlled prop: the component does **not** update it itself. Handle the `dismiss` event and assign the new value to `open` yourself, or the change will not take effect.
+
+### Slots
+
+| Slot | Required | Allowed tag names | Description |
+| --- | --- | --- | --- |
+| _(default)_ | no | — | Default slot for the popover content. Ignored when the `description` prop is set, which takes precedence. |
+| `button` | no | — | Renders a custom trigger button. When used, the default info button is replaced. |
+
+### CSS Variables
+
+| CSS Variable | Default | Description |
+| --- | --- | --- |
+| `--p-popover-w` | `max-content` | Width of the popover. |
+| `--p-popover-h` | `auto` | Height of the popover. |
+| `--p-popover-min-w` | `0px` | Min width of the popover. |
+| `--p-popover-min-h` | `auto` | Min height of the popover. |
+| `--p-popover-max-w` | `min(calc(100dvw - 16px), 48ch)` | Max width of the popover. |
+| `--p-popover-max-h` | `calc(100dvh - 16px)` | Max height of the popover. |
+| `--p-popover-px` | `16px` | Horizontal padding of the popover. It is recommended to apply an existing Porsche Design System spacing token, e.g. the CSS declaration `--p-popover-px: var(--p-spacing-static-md)`, the Tailwind CSS arbitrary property `[--p-popover-px:var(--spacing-static-md)]` or the equivalent SCSS/JS token. |
+| `--p-popover-py` | `16px` | Vertical padding of the popover. It is recommended to apply an existing Porsche Design System spacing token, e.g. the CSS declaration `--p-popover-py: var(--p-spacing-static-sm)`, the Tailwind CSS arbitrary property `[--p-popover-py:var(--spacing-static-sm)]` or the equivalent SCSS/JS token. |
+| `--p-popover-radius` | `12px` | Border radius of the popover. It is recommended to apply an existing Porsche Design System border-radius token, e.g. the CSS declaration `--p-popover-radius: var(--p-radius-lg)`, the Tailwind CSS arbitrary property `[--p-popover-radius:var(--radius-lg)]` or the equivalent SCSS/JS token. |
+
+## Examples
+
+| Example | When to use | File |
+| --- | --- | --- |
+| Default | Minimal default configuration. | [./examples/Default.tsx](./examples/Default.tsx) |
+| Slotted button | The `p-popover` component can also be used with a **slotted button** via the `button` slot, allowing you to provide a custom button element. | [./examples/SlottedButton.tsx](./examples/SlottedButton.tsx) |

package/skill/references/components/p-radio-group/examples/Default.tsx

@@ -0,0 +1,17 @@
+import React from 'react';
+import { PRadioGroup, PRadioGroupOption } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PRadioGroup name="options" label="Some Label" description="Some description">
+        <PRadioGroupOption value="a" label="Option A"></PRadioGroupOption>
+        <PRadioGroupOption value="b" label="Option B"></PRadioGroupOption>
+        <PRadioGroupOption value="c" label="Option C"></PRadioGroupOption>
+        <PRadioGroupOption value="d" label="Option D"></PRadioGroupOption>
+        <PRadioGroupOption value="e" label="Option E"></PRadioGroupOption>
+        <PRadioGroupOption value="f" label="Option F"></PRadioGroupOption>
+      </PRadioGroup>
+    </>
+  )
+}

package/skill/references/components/p-radio-group/examples/Form.tsx

@@ -0,0 +1,53 @@
+import React from 'react';
+import {
+  PButton,
+  PRadioGroup,
+  PRadioGroupOption,
+  type PRadioGroupProps,
+  PText,
+  type RadioGroupChangeEventDetail,
+} from '@porsche-design-system/components-react';
+import { FormEvent, useState } from 'react';
+
+export const Example = () => {
+  const [form, setForm] = useState({ myRadioGroup: '' });
+  const [lastSubmittedData, setLastSubmittedData] = useState<any>();
+
+  const onChange = (e: CustomEvent<RadioGroupChangeEventDetail>) => {
+    const { name, value } = e.target as HTMLElement & PRadioGroupProps;
+    setForm((prev) => ({
+      ...prev,
+      [name]: value,
+    }));
+  };
+
+  const onSubmit = (e: FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    setLastSubmittedData(JSON.stringify(form));
+  };
+
+  const onReset = (e: FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    setForm({ myRadioGroup: '' });
+  };
+
+  return (
+    <>
+      <form onSubmit={onSubmit} onReset={onReset} className="flex flex-col gap-fluid-sm">
+        <PRadioGroup name="myRadioGroup" label="Some Label" value={form.myRadioGroup} onChange={onChange}>
+          <PRadioGroupOption label="Option A" value="a"></PRadioGroupOption>
+          <PRadioGroupOption label="Option B" value="b"></PRadioGroupOption>
+          <PRadioGroupOption label="Option C" value="c"></PRadioGroupOption>
+          <PRadioGroupOption label="Option D" value="d"></PRadioGroupOption>
+          <PRadioGroupOption label="Option E" value="e"></PRadioGroupOption>
+          <PRadioGroupOption label="Option F" value="f"></PRadioGroupOption>
+        </PRadioGroup>
+        <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/skill/references/components/p-radio-group/examples/Slots.tsx

@@ -0,0 +1,69 @@
+import React from 'react';
+import { PPopover, PRadioGroup, PRadioGroupOption } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PRadioGroup state="error" value="a">
+        <span slot="label">
+          Some slotted label with a 
+          <a href="https://designsystem.porsche.com" className="underline">
+            link
+          </a>
+           text and a "label-after" slot.
+        </span>
+        <PPopover slot="label-after">
+          Some Popover description
+        </PPopover>
+        <span slot="description">
+          Some slotted description with a 
+          <a href="https://designsystem.porsche.com" className="underline">
+            link
+          </a>
+          .
+        </span>
+        <span slot="message">
+          Some slotted error message with a 
+          <a href="https://designsystem.porsche.com" className="underline">
+            link
+          </a>
+          .
+        </span>
+        <PRadioGroupOption value="a">
+          <span slot="label">
+            <img src="assets/911.png" alt="" className="object-contain inline-block align-middle -mt-2 me-static-sm w-[70px]" />
+            Some slotted label with custom content and a "label-after" slot
+          </span>
+          <PPopover slot="label-after">
+            Option A with slotted label and a popover 
+          </PPopover>
+        </PRadioGroupOption>
+        <PRadioGroupOption value="b">
+          <span slot="label">
+            Option B with slotted label
+          </span>
+        </PRadioGroupOption>
+        <PRadioGroupOption value="c" disabled="true">
+          <span slot="label">
+            Disabled Option C with slotted label, a nested 
+            <a href="https://www.porsche.com" className="underline">
+              link
+            </a>
+             and a label-after slot.
+          </span>
+          <PPopover slot="label-after">
+            Some information about the disabled state.
+          </PPopover>
+        </PRadioGroupOption>
+        <PRadioGroupOption value="d">
+          <span slot="label">
+            Option C with slotted label and a nested 
+            <a href="https://www.porsche.com" className="underline">
+              link
+            </a>
+          </span>
+        </PRadioGroupOption>
+      </PRadioGroup>
+    </>
+  )
+}

package/skill/references/components/p-radio-group/p-radio-group.md

@@ -0,0 +1,157 @@
+# p-radio-group
+
+The `p-radio-group` component is a versatile custom form element that enables the selection of a single option.
+
+> **Attention**
+>
+> The `blur` event is emitted whenever the focused `p-radio-group-option` changes — not only when the entire `p-radio-group` loses focus. This means that switching between options within the same group will also trigger a `blur` event for the previously focused option.
+
+Options are slotted using the `p-radio-group-option` component. Each option needs to have an assigned value, which can be passed via an attribute or property and needs to be of type string. Initial selection states can only be achieved using the value property on the `p-radio-group` component. If an option should be visible but not selectable, it can be disabled by using the `disabled` attribute.
+
+A `label` is a caption which informs the user what information a particular form field is asking for. The `p-radio-group` 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 best practice to provide a descriptive label text for screen readers.
+
+## Usage
+
+### Do:
+
+- Use to enable a user to select one value from a predefined list. Use as soon as two options are mutually exclusive.
+- Use [Checkbox](../p-checkbox/p-checkbox.md) instead if there is only one option.
+- Use when the user should see all available options.
+- Consider using the [Segmented Control](../p-segmented-control/p-segmented-control.md) for 5 options or fewer.
+- Keep the label text short and descriptive (one or two words).
+- Select one option by default in a group of radio buttons, except for cases where a pre-selection can lead to wrong assumptions.
+- Align radio buttons with more than 2 items vertically left-aligned.
+
+### Don't:
+
+- Don't use a radio Button for a large number of items (≥ 7), use the [Select](../p-select/p-select.md) or [Segmented Control](../p-segmented-control/p-segmented-control.md) component instead.
+
+---
+
+## Related Components
+
+- [Checkbox](../p-checkbox/p-checkbox.md)
+- [Segmented Control](../p-segmented-control/p-segmented-control.md)
+- [Select](../p-select/p-select.md)
+
+## Accessibility support
+
+### Keyboard
+
+| Key / state | Function |
+| --- | --- |
+| `Tab`, `Shift-Tab` | Moves focus to the next (or previous) focusable element. |
+| `Arrow left`, `Arrow right`, `Down Arrow` `Up Arrow` | Activates and moves focus to the next/prev radio button in a group. |
+
+### ARIA enhancements
+
+#### Internal **ARIA** that is managed by the component:
+
+| ARIA | Usage |
+| --- | --- |
+| `aria-labelledby="IDREF"` | Defines the accessible name. |
+| `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-required="true"` | Indicates if the element is required. |
+
+## 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** provide a clear group `label` that describes the choice being made.
+- **Do** use meaningful option labels so each choice is understandable out of context.
+- **Do** use the component state/message API so validation and status changes are announced.
+- **Don't** rely on adjacent text instead of the group `label` prop.
+- **Don't** use `hide-label` without an accessible name.
+
+## Tests
+
+### Automated
+
+| Technology | Support |
+| --- | --- |
+| AXE-Core (WCAG 2.2 AA, Best-Practice) | ✅ |
+| High-Contrast Mode (light/dark) | ✅ |
+| Text-Zoom (200%) | ✅ |
+
+### Manual
+
+| Technology | Support |
+| --- | --- |
+| Keyboard | ✅ |
+| Screen reader (VoiceOver, NVDA) | ⚠️(Note: VoiceOver/NVDA do not announce the number of options correctly when used with Safari or Chrome) |
+
+## API
+
+### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `compact` | `boolean` | `false` | Reduces the spacing between radio options for use in dense layouts where vertical space is limited. |
+| `description` | `string` | `''` | Sets a supplementary description displayed below the label to give users additional guidance about the radio group. |
+| `direction` | `'row'` `'column'`<br>`BreakpointCustomizable<RadioGroupDirection>` | `'column'` | Sets the layout direction of the radio options. Use `column` to stack them vertically or `row` to arrange them horizontally. Supports responsive breakpoint values. |
+| `disabled` | `boolean` | `false` | Disables all radio options in the group, preventing selection and excluding the value from form submissions. |
+| `form` | `string` | `undefined` | Associates the radio group with a form element by its ID when the group is not a direct descendant of that form. |
+| `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 radio group to identify the group's purpose. |
+| `loading` _(experimental)_ | `boolean` | `false` | @experimental Disables all radio options and shows a spinner to indicate a background loading operation. |
+| `message` | `string` | `''` | Sets the validation feedback message displayed below the radio group when `state` is `success` or `error`. |
+| `name` _(required)_ | `string` | `undefined` | Sets the shared name attribute for all radio buttons in the group, grouping them for mutually exclusive selection. |
+| `required` | `boolean` | `false` | Marks the radio group as required so the form cannot be submitted until one option is selected. |
+| `state` | `'none'` `'error'` `'success'` | `'none'` | Sets the validation state of the radio group, controlling its visual appearance and feedback message style (`none`, `success`, `error`). |
+| `value` | `string` | `''` | Sets the currently selected value that pre-selects the matching radio option and reflects user changes. |
+
+### Events
+
+| Event | Type | Description |
+| --- | --- | --- |
+| `blur` | `CustomEvent<void>` | Emitted when the radio group loses focus after the user interacts with it, useful for triggering validation on blur. |
+| `change` | `CustomEvent<RadioGroupChangeEventDetail>`<br>`Event` | Emitted when the user selects a different option, carrying the new value and the native event in the event detail. |
+
+### 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. |
+| _(default)_ | no | — | Default slot for the p-radio-group-option tags. |
+| `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. |
+
+## Sub-components
+
+These tags are only valid inside the parent(s) listed under each one — often this component, but some are shared and list a different parent (e.g. a tag documented here via a common ancestor). Their APIs come from the same authoritative `component-meta` as the parent above.
+
+### `p-radio-group-option`
+
+Allowed parent: `p-radio-group`.
+
+#### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `disabled` | `boolean` | `false` | Prevents this option from being selected and excludes its value from form submissions while it is disabled. |
+| `label` | `string` | `undefined` | Sets the visible label text displayed next to the radio button that the user reads to identify the option. |
+| `loading` _(experimental)_ | `boolean` | `false` | @experimental Disables this option and shows a spinner to indicate that this particular option is in a loading state. |
+| `value` | `string` | `undefined` | Sets the value submitted with the form data when this radio option is selected within its parent group. |
+
+#### 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`). |
+
+## Examples
+
+| Example | When to use | File |
+| --- | --- | --- |
+| Default | Minimal default configuration. | [./examples/Default.tsx](./examples/Default.tsx) |
+| Form | The `p-radio-group` 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` or `message` need markup such as a link. | [./examples/Slots.tsx](./examples/Slots.tsx) |

package/skill/references/components/p-scroller/examples/Default.tsx

@@ -0,0 +1,51 @@
+import React from 'react';
+import { PScroller, PTag } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PScroller className="max-w-[600px] whitespace-nowrap">
+        <PTag className="me-static-md" color="primary">
+          <button type="button">
+            Some tag content
+          </button>
+        </PTag>
+        <PTag className="me-static-md" color="notification-info-soft">
+          <button type="button">
+            Some tag content
+          </button>
+        </PTag>
+        <PTag className="me-static-md" color="notification-warning-soft">
+          <button type="button">
+            Some tag content
+          </button>
+        </PTag>
+        <PTag className="me-static-md" color="primary">
+          <button type="button">
+            Some tag content
+          </button>
+        </PTag>
+        <PTag className="me-static-md" color="notification-info-soft">
+          <button type="button">
+            Some tag content
+          </button>
+        </PTag>
+        <PTag className="me-static-md" color="notification-warning-soft">
+          <button type="button">
+            Some tag content
+          </button>
+        </PTag>
+        <PTag className="me-static-md" color="primary">
+          <button type="button">
+            Some tag content
+          </button>
+        </PTag>
+        <PTag color="notification-info-soft">
+          <button type="button">
+            Some tag content
+          </button>
+        </PTag>
+      </PScroller>
+    </>
+  )
+}

package/skill/references/components/p-scroller/examples/Height.tsx

@@ -0,0 +1,26 @@
+import React from 'react';
+import { PScroller, PTagDismissible } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PScroller className="max-w-[600px] whitespace-nowrap">
+        <PTagDismissible className="me-static-md">
+          Some tag content
+        </PTagDismissible>
+        <PTagDismissible className="me-static-md">
+          Some tag content
+        </PTagDismissible>
+        <PTagDismissible className="me-static-md">
+          Some tag content
+        </PTagDismissible>
+        <PTagDismissible className="me-static-md">
+          Some tag content
+        </PTagDismissible>
+        <PTagDismissible className="me-static-md">
+          Some tag content
+        </PTagDismissible>
+      </PScroller>
+    </>
+  )
+}

package/skill/references/components/p-scroller/examples/ScrollToPosition.tsx

@@ -0,0 +1,58 @@
+import React from 'react';
+import {
+  PButton,
+  PScroller,
+  PTagDismissible,
+  type ScrollerScrollToPosition,
+} from '@porsche-design-system/components-react';
+import { useCallback, useState } from 'react';
+
+export const Example = () => {
+  const style = `
+      p-scroller > *:not(:last-child) {
+        margin-right: 1rem;
+      }
+
+      button {
+        margin: 0 1rem 1rem 0;
+      }
+  `;
+
+  const [scrollToPosition, setScrollToPosition] = useState<ScrollerScrollToPosition>({
+    scrollPosition: 220,
+    isSmooth: false,
+  });
+
+  const onClick = useCallback(
+    (scrollPosition: number) => () => {
+      setScrollToPosition({ scrollPosition: scrollPosition, isSmooth: true });
+    },
+    []
+  );
+
+  return (
+    <>
+      <style dangerouslySetInnerHTML={{ __html: style }} />
+
+      <div className="flex gap-fluid-sm">
+        <PButton type="button" onClick={onClick(0)} compact={true}>
+          Scroll to start
+        </PButton>
+        <PButton type="button" onClick={onClick(220)} compact={true}>
+          Scroll to middle
+        </PButton>
+        <PButton type="button" onClick={onClick(720)} compact={true}>
+          Scroll to end
+        </PButton>
+      </div>
+
+      <div style={{ maxWidth: '400px', whiteSpace: 'nowrap' }} className="mt-fluid-sm">
+        <PScroller scrollToPosition={scrollToPosition}>
+          <PTagDismissible>START - some tag content</PTagDismissible>
+          <PTagDismissible>MIDDLE - some tag content</PTagDismissible>
+          <PTagDismissible>END - some tag content</PTagDismissible>
+        </PScroller>
+      </div>
+    </>
+  );
+};

package/skill/references/components/p-scroller/p-scroller.md

@@ -0,0 +1,93 @@
+# p-scroller
+
+The `p-scroller` component forces its child nodes to be rendered horizontally next to each other. In case not enough viewport space is given a clickable scroll indicator is shown and the elements become scrollable.
+
+As soon as the slotted element(s) exceed the viewport / their respective container, scroll indicators are shown.
+
+If the `p-scroller` component is accessed by keyboard navigation and is focused, scrolling via `arrow right` and `arrow left` is possible. If `p-scroller` contains focusable element(s) these can be also accessed by keyboard navigation.
+
+## Usage
+
+### Do:
+
+- Use when an item or a group of items do not fit into the viewport width and horizontal scrolling is needed.
+- Use it with elements of the same type, appearance, and function that are aligned horizontally.
+- Use the Surface variant if the component is used on the surface background.
+- Use it with one or more focusable elements.
+- Use in components such as Tabs, Table, and Stepper.
+
+### Don't:
+
+- Don't place important actions or information for customer flow within the scroller.
+- Don't use text that should not have line breaks in the scroller.
+- Don't assume that elements within a scroller are affected by breakpoints and viewport size as they are not.
+
+---
+
+## Related Components
+
+- [Tabs](../p-tabs/p-tabs.md)
+- [Table](../p-table/p-table.md)
+- [Stepper](../p-stepper-horizontal/p-stepper-horizontal.md)
+
+## Accessibility support
+
+### Keyboard
+
+| Key / state | Function |
+| --- | --- |
+| `Tab`, `Shift-Tab` | Moves focus to the scroll container or to next (or previous) focusable element. |
+| `Arrow left`, `Arrow right` | Scrolls the container. |
+
+### ARIA enhancements
+
+#### External **ARIA** provided by the `aria` property:
+
+| ARIA | Usage |
+| --- | --- |
+| `role="VALUE"` | Defines the semantic role of the scroll container (e.g. `list`, `tablist`). |
+| `aria-label="STRING"` | Defines an accessible name when the scroll region purpose is not obvious. |
+| `aria-description="STRING"` | Adds supplementary context for the scroll region. |
+
+## Development considerations
+
+### Common do's and don'ts
+
+- **Do** provide an accessible name through the `aria` prop when the scroll region purpose is not obvious from context.
+- **Do** pass `aria-label` and `aria-description` via the `aria` prop, not as host attributes.
+- **Don't** add native `aria-*` attributes directly on the component host.
+
+## API
+
+### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `alignScrollIndicator` _(deprecated)_ | `'top'` `'center'` | `'center'` | @deprecated since v4.0.0, will be removed with next major release, has no effect anymore. |
+| `aria` | `ScrollerAriaAttribute` | `undefined` | Sets ARIA role and attributes on the scroller's scroll container, useful for tablist navigation patterns and additional accessibility context. |
+| `compact` | `boolean` | `undefined` | Reduces the scroller's padding and the gap between slotted items for use in dense layouts. |
+| `scrollbar` | `boolean` | `false` | Shows the browser's native scrollbar inside the scroller, in addition to the scroll indicator arrows. |
+| `scrollToPosition` _(deprecated)_ | `ScrollerScrollToPosition` | `undefined` | @deprecated since v4.0.0, use native `scrollIntoView()` on the slotted element itself. |
+| `sticky` _(experimental)_ | `boolean` | `false` | @experimental Makes the indicator sticky at the top or bottom while scrolling depending on the scroll direction. |
+
+### Slots
+
+| Slot | Required | Allowed tag names | Description |
+| --- | --- | --- | --- |
+| _(default)_ | no | — | Default slot for the scroller content. |
+
+### CSS Variables
+
+| CSS Variable | Default | Description |
+| --- | --- | --- |
+| `--p-scroller-gap` | `8px` | Defines the gap between slotted nodes. |
+| `--p-scroller-indicator-top` | `0px` | Defines the distance from the top of the viewport at which the indicator sticks when scrolling down and `sticky` is enabled. |
+| `--p-scroller-indicator-bottom` | `0px` | Defines the distance from the bottom of the viewport at which the indicator sticks when scrolling up and `sticky` is enabled. |
+
+## Examples
+
+| Example | When to use | File |
+| --- | --- | --- |
+| Default | Minimal default configuration. | [./examples/Default.tsx](./examples/Default.tsx) |
+| Height | The height of `p-scroller` depends on the height of its content. | [./examples/Height.tsx](./examples/Height.tsx) |
+| Scroll to position | The `p-scroller` component provides the `scrollToPosition` property. | [./examples/ScrollToPosition.tsx](./examples/ScrollToPosition.tsx) |