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

package/skills/pds-knowledge-react/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/skills/pds-knowledge-react/references/components/p-scroller/p-scroller.md

@@ -0,0 +1,97 @@
+# 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.
+
+## Integration examples
+
+See [accessibility integration examples](./accessibility.md) for paired anti-pattern and recommended implementations.
+
+## 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) |

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/skills/pds-knowledge-react/references/components/p-segmented-control/examples/Default.tsx

@@ -0,0 +1,26 @@
+import React from 'react';
+import { PSegmentedControl, PSegmentedControlItem } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PSegmentedControl label="Some Label" description="Some description">
+        <PSegmentedControlItem value="1">
+          Option 1
+        </PSegmentedControlItem>
+        <PSegmentedControlItem value="2">
+          Option 2
+        </PSegmentedControlItem>
+        <PSegmentedControlItem value="3">
+          Option 3
+        </PSegmentedControlItem>
+        <PSegmentedControlItem value="4">
+          Option 4
+        </PSegmentedControlItem>
+        <PSegmentedControlItem value="5">
+          Option 5
+        </PSegmentedControlItem>
+      </PSegmentedControl>
+    </>
+  )
+}

package/skills/pds-knowledge-react/references/components/p-segmented-control/examples/Form.tsx

@@ -0,0 +1,52 @@
+import React from 'react';
+import {
+  PButton,
+  PSegmentedControl,
+  PSegmentedControlItem,
+  type PSegmentedControlProps,
+  PText,
+  type SegmentedControlChangeEventDetail,
+} from '@porsche-design-system/components-react';
+import { FormEvent, useState } from 'react';
+
+export const Example = () => {
+  const [form, setForm] = useState({ mySegmentedControl: undefined });
+  const [lastSubmittedData, setLastSubmittedData] = useState<any>();
+
+  const onChange = (e: CustomEvent<SegmentedControlChangeEventDetail>) => {
+    const { name, value } = e.target as HTMLElement & PSegmentedControlProps;
+    setForm((prev) => ({
+      ...prev,
+      [name]: value,
+    }));
+  };
+
+  const onSubmit = (e: FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    setLastSubmittedData(JSON.stringify(form));
+  };
+
+  const onReset = (e: FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    setForm({ mySegmentedControl: undefined });
+  };
+
+  return (
+    <>
+      <form onSubmit={onSubmit} onReset={onReset} className="flex flex-col gap-fluid-sm">
+        <PSegmentedControl name="mySegmentedControl" value={form.mySegmentedControl} onChange={onChange}>
+          <PSegmentedControlItem value={1}>Option 1</PSegmentedControlItem>
+          <PSegmentedControlItem value={2}>Option 2</PSegmentedControlItem>
+          <PSegmentedControlItem value={3}>Option 3</PSegmentedControlItem>
+          <PSegmentedControlItem value={4}>Option 4</PSegmentedControlItem>
+          <PSegmentedControlItem value={5}>Option 5</PSegmentedControlItem>
+        </PSegmentedControl>
+        <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-segmented-control/examples/Slots.tsx

@@ -0,0 +1,54 @@
+import React from 'react';
+import { PPopover, PSegmentedControl, PSegmentedControlItem } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PSegmentedControl state="error">
+        <span slot="label" id="some-label-id">
+          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" id="some-description-id">
+          Some description with a 
+          <a href="https://designsystem.porsche.com" className="underline">
+            link
+          </a>
+          .
+        </span>
+        <span slot="message" id="some-message-id">
+          Some error message with a 
+          <a href="https://designsystem.porsche.com" className="underline">
+            link
+          </a>
+          .
+        </span>
+        <PSegmentedControlItem value="1">
+          Option 1
+        </PSegmentedControlItem>
+        <PSegmentedControlItem value="2">
+          Option 2
+        </PSegmentedControlItem>
+        <PSegmentedControlItem value="3">
+          Option 3
+        </PSegmentedControlItem>
+        <PSegmentedControlItem value="4">
+          Option 4
+        </PSegmentedControlItem>
+        <PSegmentedControlItem value="5">
+          Option 5
+        </PSegmentedControlItem>
+      </PSegmentedControl>
+    </>
+  )
+}

package/skills/pds-knowledge-react/references/components/p-segmented-control/examples/WithLabels.tsx

@@ -0,0 +1,26 @@
+import React from 'react';
+import { PSegmentedControl, PSegmentedControlItem } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PSegmentedControl value="1">
+        <PSegmentedControlItem value="1" label="Label">
+          Option 1
+        </PSegmentedControlItem>
+        <PSegmentedControlItem value="2" label="Label">
+          Option 2
+        </PSegmentedControlItem>
+        <PSegmentedControlItem value="3" label="Label">
+          Option 3
+        </PSegmentedControlItem>
+        <PSegmentedControlItem value="4" label="Label" disabled={true}>
+          Option 4
+        </PSegmentedControlItem>
+        <PSegmentedControlItem value="5" label="Label">
+          Option 5
+        </PSegmentedControlItem>
+      </PSegmentedControl>
+    </>
+  )
+}

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

@@ -0,0 +1,166 @@
+# p-segmented-control
+
+The `p-segmented-control` component is similar to the native `select` element while showing all available options right away.
+
+It even behaves like a `select` where it can be controlled by setting the current value. However, it is not required and you could purely rely on the change event.
+
+By default the `p-segmented-control` displays all options in **equal** size based on its largest option. If the `no-wrap` property is set to `true`, the items will be rendered inline (shrinked to their initial size) with an optional scroller.
+
+Each option needs to be rendered by using a `p-segmented-control-item` child component where the `value` property is **mandatory** in order to emit a useful change event.
+
+## Usage
+
+### Do:
+
+- Use to present a set of selectable options at once.
+- Use it for selecting from 2-5 short, consistent options.
+- Use them over other selection controls to reduce cognitive load.
+- Pair options with icons to improve visual recognition.
+- Use icons only when the context meaning is really clear.
+- Use preselection when the result is visible by default.
+- Use with no selection when a selection by the user is necessary to show the result.
+- Use it with a short indication for the unit (such as km, €, %, or $) when possible.
+- Use for horizontal and/or vertical display of options.
+
+### Don't:
+
+- Don't use it to filter or navigate content (use [Tabs](../p-tabs/p-tabs.md) instead).
+- Don't use it for more than 5 options (use the [Select](../p-select/p-select.md) component).
+- Don't use it with mixed values (use [Radio Group](../p-radio-group/p-radio-group.md) or [Select](../p-select/p-select.md) instead).
+- Don't exceed maximum width so the values turn multiline.
+
+---
+
+## Related components
+
+- [Select](../p-select/p-select.md)
+- [Radio Button](../p-radio-group/p-radio-group.md)
+- [Tabs](../p-tabs/p-tabs.md)
+
+## Accessibility support
+
+### Keyboard
+
+| Key / state | Function |
+| --- | --- |
+| `Tab`, `Shift-Tab` | Moves focus to the next (or previous) focusable element. |
+| `Space`, `Enter` | Activates the control. |
+
+### ARIA enhancements
+
+#### External **ARIA** provided by the `aria` property:
+
+| ARIA | Usage |
+| --- | --- |
+| `aria-label="STRING"` | Defines a string value that labels the control item itself. |
+
+#### Internal **ARIA** that is managed by the component:
+
+| ARIA | Usage |
+| --- | --- |
+| `role="group"` | Identifies a set of user interface objects. |
+| `aria-pressed="BOOLEAN"` | Provides the current state of the control. |
+| `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. |
+| `aria-description="STRING"` | Provides additional content for states. |
+
+## Development considerations
+
+### Labelling
+
+Provide a descriptive `label` on the wrapper component to give context for the group of options. If a more detailed label is needed for each **control item**, use the `aria` property on the control item itself, e.g.: `<p-segmented-control-item value="xs" aria="{ 'aria-label': 'Size x-small' }">XS</p-segmented-control-item>`.
+
+If an **icon only** is used, it is mandatory to also provide an accessible name through the `aria` property of the control item.
+
+### 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** pass item-level ARIA through the `aria` prop on `p-segmented-control-item`, especially for icon-only items.
+- **Do** use the component state/message API so validation and status changes are announced.
+- **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
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `columns` | `'auto'` `1` `2` `3` `4` `5` `6` `7` `8` `9` `10` `11` `12` `13` `14` `15` `16` `17` `18` `19` `20` `21` `22` `23` `24` `25`<br>`BreakpointCustomizable<SegmentedControlColumns>` | `'auto'` | Sets the number of equal-width columns for the item layout. Use `auto` to distribute items based on their content width. Supports responsive breakpoint values. |
+| `compact` | `boolean` | `false` | Reduces the item height and spacing for use in dense layouts where vertical space is limited. |
+| `description` | `string` | `''` | Sets a supplementary description displayed below the label to give users additional context about the segmented control. |
+| `disabled` | `boolean` | `false` | Prevents user interaction with all items in the segmented control and excludes the value from form submissions. |
+| `form` | `string` | `undefined` | Associates the segmented control with a form element by its ID when it 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 segmented control to describe the group of options. |
+| `message` | `string` | `''` | Sets the validation feedback message displayed below the segmented control when `state` is `success` or `error`. |
+| `name` | `string` | `undefined` | Sets the name of the control submitted with the form data to identify the selected value on the server. |
+| `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. |
+
+### Events
+
+| Event | Type | Description |
+| --- | --- | --- |
+| `blur` | `CustomEvent<void>` | Emitted when the segmented control loses focus, useful for triggering validation on blur. |
+| `change` | `CustomEvent<SegmentedControlChangeEventDetail>`<br>`{ value: string | number }` | Emitted when the user selects a different item, carrying the new value in the event detail. |
+
+### Controlled properties
+
+- `value` — a controlled prop, but the component also updates it internally. Listen for the `change` event to observe changes; you do not have to write the value back.
+
+### 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-segmented-control-item` 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-segmented-control-item`
+
+Allowed parent: `p-segmented-control`.
+
+#### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `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. |
+| `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**. |
+
+#### Slots
+
+| Slot | Required | Allowed tag names | Description |
+| --- | --- | --- | --- |
+| _(default)_ | no | — | Default slot for the content. |
+
+## Examples
+
+| Example | When to use | File |
+| --- | --- | --- |
+| Default | Minimal default configuration. | [./examples/Default.tsx](./examples/Default.tsx) |
+| Form | The `p-segmented-control` can be integrated into a form in two ways: **controlled** or **uncontrolled**, depending on your needs. | [./examples/Form.tsx](./examples/Form.tsx) |
+| With Labels | Additional meta information can be displayed by setting a `label` on each child. | [./examples/WithLabels.tsx](./examples/WithLabels.tsx) |
+| Slots | Use named slots when `label`, `description` or `message` need markup such as a link. | [./examples/Slots.tsx](./examples/Slots.tsx) |