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

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

@@ -0,0 +1,10 @@
+import React from 'react';
+import { PSpinner } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PSpinner aria={{'aria-label': 'Loading page content'}}></PSpinner>
+    </>
+  )
+}

package/skill/references/components/p-spinner/examples/ResponsiveSize.tsx

@@ -0,0 +1,10 @@
+import React from 'react';
+import { PSpinner } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PSpinner size={{'base': 'sm', 'l': '2xl'}} aria={{'aria-label': 'Loading page content'}}></PSpinner>
+    </>
+  )
+}

package/skill/references/components/p-spinner/examples/Size.tsx

@@ -0,0 +1,13 @@
+import React from 'react';
+import { PSpinner, PText } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PText className="text-[48px]" size="inherit">
+        <PSpinner className="me-static-sm" size="inherit" aria={{'aria-label': 'Loading page content'}}></PSpinner>
+        Some text
+      </PText>
+    </>
+  )
+}

package/skill/references/components/p-spinner/examples/SizeCssVar.tsx

@@ -0,0 +1,10 @@
+import React from 'react';
+import { PSpinner } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PSpinner className="[--p-spinner-size:48px]" aria={{'aria-label': 'Loading page content'}}></PSpinner>
+    </>
+  )
+}

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

@@ -0,0 +1,96 @@
+# p-spinner
+
+The `p-spinner` component indicates an indeterminate ongoing process and should be used when users must wait for loading or processing to finish.
+
+There are unavoidable moments when the user has to wait for more than 1 second (for example due to technical processing of information or requests). These moments should be bridged with a good user feedback in order to not leave the user uncertain about what's currently happening - also to avoid a high bounce rate and to obtain a positive impression of your website or application.
+
+For ongoing operations between 2-10 seconds, where the loading progress cannot be determined, use a **Spinner** (looped indicator) to inform the user about an ongoing operation. Use it either stand-alone (for example as page loader) or within components, such as in Buttons to indicate progress after clicking "save".
+
+## Usage
+
+### Do:
+
+- Use when the user has to wait for more than 1 second.
+- Use either stand-alone or within components (e.g. in Buttons to indicate progress after clicking "save“).
+- Use vertically and horizontally centered within the referring area.
+- Use a blocking layer for the whole screen when the user is not supposed to start another activity.
+- Include simple text to explain why the user is waiting.
+- Disable the component while the spinner is visible if it is triggered by an interaction.
+
+### Don't:
+
+- Don't use too many Spinners at the same time within a page or application.
+- Don't use Spinners for delays of more than 10 seconds without providing a progress bar showing the estimated waiting time.
+- Don't use threatening text such as "Don't click again" to prevent the user from clicking twice.
+
+## Accessibility support
+
+### ARIA enhancements
+
+#### External **ARIA** provided by the `aria` property:
+
+| ARIA | Usage |
+| --- | --- |
+| `aria-label` | Defines a string value that labels the live region. |
+
+#### Internal **ARIA** that is managed by the component:
+
+| ARIA | Usage |
+| --- | --- |
+| `role="alert"` | Provided message is announced. |
+
+## Development considerations
+
+### Announcing loading messages
+
+To provide feedback to screen reader users, it is mandatory to announce the loading state of the spinner. This can be achieved in the following ways:
+
+- Pre-rendering the component in the DOM.
+- Providing a meaningful loading state message through the `aria` property, e.g. `aria="{ 'aria-label': 'Start/End loading content'}"`.
+
+### Common do's and don'ts
+
+- **Do** pre-render the spinner when loading feedback must be announced.
+- **Do** provide a specific loading message through the `aria` prop.
+- **Don't** mount the spinner only at the moment loading starts without a label.
+
+## Notes
+
+### Disable animation
+
+For automated visual regression tests, the spinner animation can be disabled by setting a global CSS variable:
+
+```
+:root {
+  --p-animation-duration: 0s !important;
+}
+```
+
+## API
+
+### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `aria` | `SpinnerAriaAttribute` | `undefined` | Sets ARIA attributes on the spinner's live region element; use `aria-label` to provide a descriptive loading message for screen readers. |
+| `color` | `'primary'` `'inherit'` | `'primary'` | Sets the color of the spinning indicator using PDS semantic color tokens (e.g. `primary`, `contrast-high`, `inherit`). |
+| `size` | `'2xs'` `'xs'` `'sm'` `'md'` `'lg'` `'xl'` `'2xl'` `'3xl'` `'4xl'` `'5xl'` `'inherit'`<br>_deprecated:_ `'small'` `'medium'` `'large'`<br>`BreakpointCustomizable<SpinnerSize>` | `'sm'` | Sets the size of the spinner using the PDS typographic scale. Use `inherit` to derive the size from the parent element's font-size. Supports responsive breakpoint values. |
+
+### CSS Variables
+
+| CSS Variable | Default | Description |
+| --- | --- | --- |
+| `--p-spinner-size` | — | Defines the width and height of the spinner. Overrides the `size` property when set. |
+| `--p-spinner-color` | — | Defines the foreground color. Overrides the `color` property when set. |
+| `--p-spinner-track-color` | — | Defines the track/background color. Overrides the `color` property when set. |
+
+## Examples
+
+| Example | When to use | File |
+| --- | --- | --- |
+| Default | Minimal default configuration. | [./examples/Default.tsx](./examples/Default.tsx) |
+| Size via Prop | There are predefined sizes for the component available which should cover most use cases. | [./examples/Size.tsx](./examples/Size.tsx) |
+| Size via CSS Variable | Instead of using the `size` prop, the size can be controlled via the custom CSS variable `--p-spinner-size`, which accepts any valid CSS length value. | [./examples/SizeCssVar.tsx](./examples/SizeCssVar.tsx) |
+| Responsive Size | The `size` property supports `BreakpointCustomizable` values, allowing you to define different sizes for each major breakpoint (`xs`, `s`, `m`, `l`, `xl`). | [./examples/ResponsiveSize.tsx](./examples/ResponsiveSize.tsx) |
+| Color via Prop | The `color` property can be set to `inherit` to derive the spinner's color from the `currentcolor` of a parent element (e.g. a `p-text`). | [./examples/Color.tsx](./examples/Color.tsx) |
+| Color via CSS Variable | Instead of using the `color` prop, the colors can be controlled via the custom CSS variables `--p-spinner-color` and `--p-spinner-track-color`, which accept any valid CSS color value. | [./examples/ColorCssVar.tsx](./examples/ColorCssVar.tsx) |

package/skill/references/components/p-stepper-horizontal/examples/Default.tsx

@@ -0,0 +1,23 @@
+import React from 'react';
+import { PStepperHorizontal, PStepperHorizontalItem } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PStepperHorizontal>
+        <PStepperHorizontalItem state="complete">
+          Step 1
+        </PStepperHorizontalItem>
+        <PStepperHorizontalItem state="warning">
+          Step 2
+        </PStepperHorizontalItem>
+        <PStepperHorizontalItem state="current">
+          Step 3
+        </PStepperHorizontalItem>
+        <PStepperHorizontalItem>
+          Step 4
+        </PStepperHorizontalItem>
+      </PStepperHorizontal>
+    </>
+  )
+}

package/skill/references/components/p-stepper-horizontal/examples/FrameworkImplementation.tsx

@@ -0,0 +1,100 @@
+import React from 'react';
+import {
+  PButton,
+  PStepperHorizontal,
+  PStepperHorizontalItem,
+  PText,
+  type StepperHorizontalItemState,
+  type StepperHorizontalUpdateEventDetail,
+} from '@porsche-design-system/components-react';
+import { useState } from 'react';
+
+type StepperHorizontalItemProps = {
+  state?: StepperHorizontalItemState;
+  name: string;
+};
+
+export const Example = () => {
+  const [steps, setSteps] = useState<StepperHorizontalItemProps[]>([
+    {
+      state: 'current',
+      name: 'Enter personal details',
+    },
+    {
+      name: 'Confirm e-mail',
+    },
+    {
+      name: 'Set password',
+    },
+  ]);
+
+  const stepContent: string[] = [
+    'A form with personal details could be displayed here.',
+    'A form with a verification code input field could be displayed here.',
+    'A form with a password input field could be displayed here.',
+  ];
+
+  const getActiveStepIndex = (steps: StepperHorizontalItemProps[]): number =>
+    steps.findIndex((step) => step.state === 'current');
+
+  const onNextPrevStep = (direction: 'next' | 'prev'): void => {
+    const newState = [...steps];
+    const activeStepIndex = getActiveStepIndex(newState);
+
+    if (direction === 'next') {
+      newState[activeStepIndex].state = 'complete';
+      newState[activeStepIndex + 1].state = 'current';
+    } else {
+      delete newState[activeStepIndex].state;
+      newState[activeStepIndex - 1].state = 'current';
+    }
+
+    setSteps(newState);
+  };
+
+  const onUpdate = (e: CustomEvent<StepperHorizontalUpdateEventDetail>): void => {
+    const { activeStepIndex } = e.detail;
+
+    const newState = [...steps];
+    for (let i = activeStepIndex + 1; i < newState.length; i++) {
+      // reset step state when going back via stepper horizontal item click
+      delete newState[i].state;
+    }
+    newState[activeStepIndex].state = 'current';
+    setSteps(newState);
+  };
+
+  return (
+    <div className="flex flex-col gap-fluid-sm">
+      <PStepperHorizontal onUpdate={onUpdate}>
+        {steps.map(({ state, name }) => (
+          <PStepperHorizontalItem key={name} state={state}>
+            {name}
+          </PStepperHorizontalItem>
+        ))}
+      </PStepperHorizontal>
+
+      {stepContent.map((content, i) => getActiveStepIndex(steps) === i && <PText key={i}>{content}</PText>)}
+
+      <div className="flex gap-fluid-sm">
+        <PButton
+          type="button"
+          icon="arrow-head-left"
+          variant="secondary"
+          onClick={() => onNextPrevStep('prev')}
+          disabled={getActiveStepIndex(steps) === 0}
+        >
+          Previous Step
+        </PButton>
+
+        <PButton
+          variant="primary"
+          disabled={getActiveStepIndex(steps) === steps.length - 1}
+          onClick={() => onNextPrevStep('next')}
+        >
+          Next Step
+        </PButton>
+      </div>
+    </div>
+  );
+};

package/skill/references/components/p-stepper-horizontal/p-stepper-horizontal.md

@@ -0,0 +1,109 @@
+# p-stepper-horizontal
+
+The `p-stepper-horizontal` component displays progress through a sequence of logical and numbered steps. It is ideal when the contents of one step depends on an earlier step. Avoid using long step names.
+
+The component does not handle the display of your content. When using the component you have to manually take care of the content to be rendered beneath. To help with this task, if a step is clicked, the component triggers an event called `change` with the index of the clicked step.
+
+**Note**: Maximum of 9 steps are supported.
+
+It is a controlled component. This means it does not contain any internal state and you got full control over its behavior.
+
+Use `p-stepper-horizontal-item`s inside the `p-stepper-horizontal` component. Each item will be rendered as a step. You have to manually manage the state of the items by setting the `state` property.
+
+The `state` property can be set to `complete` when a step is complete, `warning` when a user has to revisit the step, `current` for the step that is in progress and `undefined`.
+
+If the `state` property is `undefined` the step renders as stateless and disabled. This can be used to prevent the user from navigating to a step which is not yet reachable. This is to be used for future steps which cannot yet be processed at the time.
+
+By clicking on a previous step, the `p-stepper-horizontal` emits the `update` event, which contains the index of the clicked step.
+
+## Usage
+
+### Do:
+
+- Use to display progress through a sequence of logical and numbered steps.
+- Use when the content of one step depends on an earlier step.
+- Use short and descriptive labels for each step.
+- Make completed steps clickable so that the user can jump back to previous steps.
+- Be aware that the component does not handle the display of your content and you will need to manually take care of the content to be rendered beneath.
+- Consider how you can simplify the component and use between 3-5 steps for the best user experience.
+
+### Don't:
+
+- Don't use long step names as it can make the component difficult to use.
+- Don't use more than 9 steps (component has a maximum of 9)
+- Don't forget that if a set of steps can not fit on the screen the stepper becomes horizontally scrollable and navigable with arrows.
+
+## Accessibility support
+
+### Keyboard
+
+| Key / state | Function |
+| --- | --- |
+| `Tab`, `Shift-Tab` | Moves focus to the scroll container or to next (or previous) focusable element. |
+| `Enter`, `Space` | Activates the completed and current step-item. |
+| `disabled` | Step-item still focusable. |
+
+### ARIA enhancements
+
+#### Internal **ARIA** that is managed by the component:
+
+| ARIA | Usage |
+| --- | --- |
+| `role="list"` | Indicates the stepper as list element. |
+| `role="listitem"` | Indicates the step-item as list-item element. |
+
+## Development considerations
+
+### Common do's and don'ts
+
+- **Do** provide descriptive text in each step item so progress is understandable out of context.
+- **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.
+
+## API
+
+### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `size` | `'small'` `'medium'`<br>`BreakpointCustomizable<StepperHorizontalSize>` | `'small'` | The font size of the step labels. |
+
+### Events
+
+| Event | Type | Description |
+| --- | --- | --- |
+| `update` | `CustomEvent<StepperHorizontalUpdateEventDetail>`<br>`{ activeStepIndex: number }` | Emitted when active step is changed. |
+
+### Slots
+
+| Slot | Required | Allowed tag names | Description |
+| --- | --- | --- | --- |
+| _(default)_ | no | — | Default slot for the `p-stepper-horizontal-item` tags. |
+
+## 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-stepper-horizontal-item`
+
+Allowed parent: `p-stepper-horizontal`.
+
+#### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `disabled` | `boolean` | `false` | Disables the stepper-horizontal-item. No events will be triggered while disabled state is active. |
+| `state` | `undefined` `'current'` `'complete'` `'warning'` | `undefined` | The current progression state of the step. Use `current` for the active step, `complete` for finished steps, `warning` for steps with issues. Leave unset for future steps. |
+
+#### 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) |
+| Framework Implementation | Below you can find an interactive example of an outlined registration process. | [./examples/FrameworkImplementation.tsx](./examples/FrameworkImplementation.tsx) |

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

@@ -0,0 +1,19 @@
+import React from 'react';
+import { useState } from 'react';
+import { PSwitch, type SwitchUpdateEventDetail } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  const [checked, setChecked] = useState(false);
+
+  const onUpdate = (e: CustomEvent<SwitchUpdateEventDetail>) => {
+    setChecked(e.detail.checked);
+  }
+
+  return (
+    <>
+      <PSwitch checked={checked} onUpdate={onUpdate}>
+        Some label
+      </PSwitch>
+    </>
+  )
+}

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

@@ -0,0 +1,103 @@
+# p-switch
+
+The `p-switch` component is a control that is used to quickly switch between two possible states. A switch is only used for these binary actions that occur immediately after the user “flips the switch”. Commonly it is used for “on/off” state.
+
+It is a controlled component. This means it does not contain any internal state, and you got full control over its behavior.
+
+The `p-switch` component can be used with a visible or hidden label, but it's recommended to keep the label visible for better accessibility whenever possible. A `label` is a caption which informs the user which action is followed by interaction. When used with hidden label, it's best practice to provide a descriptive label text for screen readers.
+
+You can use native `click`, `focus`, `focusin`, `blur` and `focusout` events on the `p-switch`.
+
+## Usage
+
+### Do:
+
+- Use it when an instant response to applied settings is required without explicit action.
+- Use to enable or disable a mode, feature, or function.
+- Use when the user is toggling independent features or behaviors.
+- Use the label to describe the affected property.
+- Use the right-aligned version for lists (especially for handling on mobile devices).
+- Use the stretched version for lists on mobile or smaller containers.
+
+### Don't:
+
+- Don't use it if a setting requires a button press before it can take effect (use a [Checkbox](../p-checkbox/p-checkbox.md) instead).
+- Don't use anything longer than two words in the label whenever possible.
+- Don't use the switch for multiple-choice questions.
+- Don't use slide Switch when an intermediate state is required (Use [Checkbox](../p-checkbox/p-checkbox.md) instead).
+- Don't use the label to describe the state of the component.
+
+---
+
+## Related Components
+
+- [Checkbox](../p-checkbox/p-checkbox.md)
+- [Button](../p-button/p-button.md)
+
+## Accessibility support
+
+### Keyboard
+
+| Key / state | Function |
+| --- | --- |
+| `Tab`, `Shift-Tab` | Moves focus to the scroll container or to next (or previous) focusable element. |
+| `Enter`, `Space` | Activates the completed and current step-item. |
+| `disabled` | Step-item still focusable. |
+
+### ARIA enhancements
+
+#### Internal **ARIA** that is managed by the component:
+
+| ARIA | Usage |
+| --- | --- |
+| `role="switch"` | Indicates the element as switch element. |
+| `aria-checked="BOOLEAN"` | Indicates the status of the switch element. |
+| `role="status"` | When `loading` prop is set, the component announces the loading state (start and finish). |
+
+## Development considerations
+
+### Labelling
+
+The switch accessible name comes from the default slot. Provide concise, descriptive text that states what the switch controls and its on/off meaning.
+
+### Common do's and don'ts
+
+- **Do** provide a clear slotted label that describes what the switch controls.
+- **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.
+
+## API
+
+### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `alignLabel` | `'start'` `'end'`<br>`BreakpointCustomizable<SwitchAlignLabel>` | `'end'` | Sets the position of the slotted label relative to the switch toggle, either before (`start`) or after (`end`) it. Supports responsive breakpoint values. |
+| `checked` | `boolean` | `false` | Reflects the switch's current on/off state and allows setting the initial checked value when the component first renders. |
+| `compact` | `boolean` | `false` | Reduces the switch size and spacing for use in dense layouts where vertical space is limited. |
+| `disabled` | `boolean` | `false` | Prevents user interaction with the switch and blocks all click and keyboard events while it is disabled. |
+| `hideLabel` | `boolean`<br>`BreakpointCustomizable<boolean>` | `false` | Hides the visible label while keeping it accessible to screen readers. Supports responsive breakpoint values. |
+| `loading` | `boolean` | `false` | Disables the switch and shows a loading spinner to indicate an ongoing asynchronous toggle operation. |
+| `stretch` | `boolean`<br>`BreakpointCustomizable<boolean>` | `false` | Expands the space between the switch toggle and its label to fill the full available width of the container. Supports responsive breakpoint values. |
+
+### Events
+
+| Event | Type | Description |
+| --- | --- | --- |
+| `update` | `CustomEvent<SwitchUpdateEventDetail>`<br>`{ checked: boolean }` | Emitted when the user toggles the switch, carrying the new `checked` state in the event detail. |
+
+### Controlled properties
+
+- `checked` — a controlled prop: the component does **not** update it itself. Handle the `update` event and assign the new value to `checked` yourself, or the change will not take effect.
+
+### Slots
+
+| Slot | Required | Allowed tag names | Description |
+| --- | --- | --- | --- |
+| _(default)_ | no | — | Default slot for the label. |
+
+## Examples
+
+| Example | When to use | File |
+| --- | --- | --- |
+| Default | Minimal default configuration. | [./examples/Default.tsx](./examples/Default.tsx) |