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

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

@@ -0,0 +1,194 @@
+# p-select
+
+The `p-select` component is a versatile custom form element that enables the selection of a single option.
+
+Options are slotted using the `p-select-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-select` component ([More Info](./p-select.md)). Options don't have a selected attribute or property. If an option should be visible but not selectable, it can be disabled by using the `disabled` attribute. If the selection isn't required or should be clearable again, you can use an empty `p-select-option` as default selection ([More Info](./p-select.md)).
+
+**Hint:** The `p-select` utilizes the [Popover API](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) to render its dropdown on the `#top-layer` which enables it to be shown correctly even when used e.g. within a scroll container.
+
+## Usage
+
+### Do:
+
+- Keep the label visible for better accessibility whenever possible.
+- Provide a descriptive label text for screen readers when using the component without a label.
+- Use it to search and choose a single option from a list — for example to trigger an action based on the selection or to navigate the user to a new position — and recommend a default option for most users.
+- Use without label only if the context clearly describes what the component is to be used for and no further explanation is required.
+- Provide a description text displayed openly and directly outside the form field when helpful for the user to get further information on the input.
+- Use the custom filter for a large number of select options (e.g. country/state select).
+- Use without preselection (mandatory field) if you don't know or need to make sure the user makes a conscious choice.
+- Use preselection (mandatory field) if you have a reason to believe one of the options is most likely or you know the default or current option.
+- Use preselection (optional field) to make it possible to go back to an empty default.
+- Use common sort order for menu items (frequency of use, alpha or numeric).
+
+### Don't:
+
+- Don't use select boxes for data that is highly familiar such as the day month or year.
+- Don't set the default to 'please select' if there's an empty field.
+- Don't use very long select boxes that require scrolling but if unavoidable make sure that when open there is only a maximum of 7 elements in the field of view without having to scroll.
+
+## Accessibility support
+
+### Keyboard
+
+#### Combobox
+
+| Key / state | Function |
+| --- | --- |
+| `Down Arrow` `Up Arrow` `Space` | - Opens the listbox if it is not already displayed without moving focus or changing selection. - DOM focus remains on the combobox. |
+| `Space` | Closes the listbox if it is displayed. |
+
+#### Listbox
+
+| Key / state | Function |
+| --- | --- |
+| `Down Arrow` `Up Arrow` | Moves visual focus to the next/previous option. |
+| `Home` `End` | Moves visual focus to the first/last option. |
+| `ESC` | Closes listbox |
+| `Enter`, `Space` | Selects an option |
+
+### ARIA enhancements
+
+#### Internal **ARIA** that is managed by the component:
+
+| ARIA | Usage |
+| --- | --- |
+| `aria-labelledby="IDREF"` | References the accessible name of the combobox. |
+| `aria-describedby="IDREF"` | References the accessible description and status messages of the combobox. |
+| `aria-label="STRING"` | References the accessible name of the listbox. |
+| `role="status"`, `role="alert"` | When `message` and `state` prop change, the status message is announced. |
+| `aria-expanded="BOOLEAN"` | Indicates that the listbox element is displayed/hidden. |
+| `aria-controls="IDREF"` | Identifies the element that serves as the listbox. |
+| `aria-hidden="true"` | If `required` attribute is set, the visible indicator is hidden from assistive technologies. |
+| `aria-haspopup="listbox"` | Indicates that the combobox will open a listbox. |
+| `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, persistent label for what the selection controls.
+- **Do** use meaningful option text so choices are understandable out of context.
+- **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** use a prompt option or adjacent text as a substitute for a field label.
+- **Don't** use very short or ambiguous option labels when context is important.
+- **Don't** use `hide-label` without an accessible name.
+
+## API
+
+### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `compact` | `boolean` | `false` | Reduces the control height and padding 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 select. |
+| `disabled` | `boolean` | `false` | Prevents user interaction with the select and excludes its value from form submissions. |
+| `dropdownDirection` | `'down'` `'up'` `'auto'` | `'auto'` | Controls whether the dropdown list opens upward (`up`) or downward (`down`), or determines the direction automatically (`auto`). |
+| `filter` | `boolean` | `false` | Shows a text input inside the dropdown that filters the visible options as the user types. Ignored when the `filter` slot is used. |
+| `form` | `string` | `undefined` | Associates the select 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 select control to identify its purpose. |
+| `message` | `string` | `''` | Sets the validation feedback message displayed below the select when `state` is `success` or `error`. |
+| `name` _(required)_ | `string` | `undefined` | Sets the name of the control submitted with the form data, identifying the selected value on the server. |
+| `required` | `boolean` | `false` | Marks the select as required so the form cannot be submitted unless a non-empty option is selected. |
+| `state` | `'none'` `'error'` `'success'` | `'none'` | Sets the validation state of the select, which controls its visual appearance and feedback message style (`none`, `success`, `error`). |
+| `value` | `string | number | null` | `undefined` | The selected value. Matches an option strictly by type and value, meaning null matches only an option with value null, undefined matches only an option with value undefined (no preselection by default), and string or number only match an option whose value has the same type and equal value. Please note that FormData always serializes values as strings, so when participating in a native (uncontrolled) form a number value is restored as string via formStateRestoreCallback and will no longer strictly match a number-typed option. This limitation only applies to native form state restoration; in controlled forms (where the consumer manages value directly via the change event), the number type is preserved end-to-end. |
+
+### Events
+
+| Event | Type | Description |
+| --- | --- | --- |
+| `blur` | `CustomEvent<void>` | Emitted when the select component loses focus, useful for triggering validation on blur. |
+| `change` | `CustomEvent<SelectChangeEventDetail>`<br>`{ name: string; value: string | number | null | undefined }` | Emitted when the user selects a different option, carrying the new value in the event detail. |
+| `toggle` | `CustomEvent<SelectToggleEventDetail>`<br>`{ open: boolean }` | Emitted when the dropdown list opens or closes, carrying the new `isOpen` state 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. |
+| `selected` | no | — | Use this slot to provide custom markup for the selected option display in the button area. |
+| _(default)_ | no | — | Default slot for the `p-select-option` tags. |
+| `options-status` | no | — | When implementing a custom filter with the `filter` slot, use this slot for loading, error and no results status. |
+| `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. |
+| `filter` | no | — | Optional slot for providing a custom `p-input-search` input. When used, the default filter input is replaced and the built-in filter logic is disabled, giving full control over filtering behavior. |
+
+## 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-multi-select-option`
+
+Allowed parents: `p-multi-select`, `p-optgroup`.
+
+#### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `disabled` | `boolean` | `false` | Disables the option, preventing it from being selected. |
+| `value` _(required)_ | `string | number` | `undefined` | Sets the value submitted with the form data when this option is selected in the parent multi-select. |
+
+#### Slots
+
+| Slot | Required | Allowed tag names | Description |
+| --- | --- | --- | --- |
+| _(default)_ | no | — | Default slot for the option text. |
+
+### `p-optgroup`
+
+Allowed parents: `p-select`, `p-multi-select`.
+
+#### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `disabled` | `boolean` | `false` | Disables all options in the group, preventing any of them from being selected. |
+| `label` | `string` | `undefined` | Sets the visible group heading displayed above the grouped options. |
+
+#### Slots
+
+| Slot | Required | Allowed tag names | Description |
+| --- | --- | --- | --- |
+| _(default)_ | no | — | Default slot for the optgroup content. |
+
+### `p-select-option`
+
+Allowed parents: `p-select`, `p-optgroup`.
+
+#### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `disabled` | `boolean` | `false` | Prevents the option from being selected and visually dims it to indicate it is unavailable. |
+| `value` | `string | number | null` | `undefined` | Sets the value submitted with the form data when this option is selected in the parent select control. |
+
+#### Slots
+
+| Slot | Required | Allowed tag names | Description |
+| --- | --- | --- | --- |
+| _(default)_ | no | — | Default slot for the option content. |
+
+## Examples
+
+| Example | When to use | File |
+| --- | --- | --- |
+| Default | Minimal default configuration. | [./examples/Default.ts](./examples/Default.ts) |
+| Form | The `p-select` can be integrated into a form in two ways: **controlled** or **uncontrolled**, depending on your needs. | [./examples/Form.ts](./examples/Form.ts) |
+| Basic example without preselection | To require the user to actively pick an option, leave the `p-select` `value` property unset (or set it to `undefined` or `null`). | [./examples/Required.ts](./examples/Required.ts) |
+| Slotted images | In order to show an icon for each option, you can optionally slot an `img` tag within the `p-select-option`. | [./examples/SlottedImages.ts](./examples/SlottedImages.ts) |
+| Slots | Use named slots when `label`, `description` or `message` need markup such as a link. | [./examples/Slots.ts](./examples/Slots.ts) |
+| Set Value | The `p-select` component behaves like regular form elements. | [./examples/SetValue.ts](./examples/SetValue.ts) |
+| With optgroups | With optgroups | [./examples/Optgroups.ts](./examples/Optgroups.ts) |
+| Custom asynchronous filtering | The `p-select` component automatically filters options based on user input. | [./examples/AsyncFilter.ts](./examples/AsyncFilter.ts) |
+| Custom option rendering | `p-select-option` only allows `#text` and `img` nodes unless the parent `p-select` provides a custom selection renderer through the `selected` slot, which also enables custom option markup. | [./examples/SelectedSlot.ts](./examples/SelectedSlot.ts) |

package/skill/references/components/p-sheet/examples/Default.ts

@@ -0,0 +1,33 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <p-button type="button" [aria]="{'aria-haspopup': 'dialog'}" (click)="onClick()">
+        Open Sheet
+      </p-button>
+
+      <p-sheet [open]="open" [aria]="{'aria-label': 'Some Heading'}" (dismiss)="onDismiss()">
+        <p-heading slot="header" size="large" tag="h2">
+          Some Heading
+        </p-heading>
+        <p-text>
+          Some Content
+        </p-text>
+      </p-sheet>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {
+  open = false;
+
+  onClick() {
+    this.open = true;
+  }
+  onDismiss() {
+    this.open = false;
+  }
+}

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

@@ -0,0 +1,121 @@
+# p-sheet
+
+The `p-sheet` is a temporary overlay to focus the user's attention on one or multiple tasks while the underlying page is still visible but interactions with it are blocked. It should be used thoughtfully and sparingly.
+
+It is a controlled component. This grants flexible control over the sheet's behavior especially whether it should stay open after user interaction like submission of a form.
+
+> **Scroll-lock**
+>
+> This component sets `overflow: hidden` on the body when opened in order to prevent background scrolling.
+>
+> This doesn't work completely reliable under iOS but is the most stable solution.
+>
+> Feel free to address this issue in an Open Source PR, if you can provide a better solution.
+>
+> **[Current implementation](https://github.com/porsche-design-system/porsche-design-system/blob/main/packages/components/src/utils/setScrollLock.ts)**
+
+Following **web standards**, the component uses the native `<dialog />` element internally which ensures proper focus handling including a **focus trap**. In addition, it's rendered on the `#top-layer` which ensures the element to be on top of the page independent of where `p-sheet` is placed in the DOM hierarchy (`z-index` is not relevant anymore and won't have any effect).
+
+The most important property of `p-sheet` is its `open` property. When it's set to `true` the sheet will be visible. In order to get notified when the sheet gets closed by clicking the `x` button, the backdrop or by pressing the `Escape` key you need to register an event listener for the `dismiss` event which is emitted by `p-sheet`.
+
+## Usage
+
+### Do:
+
+- Use an sheet only for critical decisions or when multiple related actions need to be presented.
+- Keep the options clear, concise, and easy to understand.
+- Limit the number of choices to avoid overwhelming the user.
+- Use descriptive labels that indicate the outcome of each action.
+- Include a cancel option to allow users to dismiss the sheet without making a selection.
+
+### Don't:
+
+- Don’t use sheets for non-essential or minor tasks.
+- Avoid presenting too many options or complex decisions.
+- Don’t use vague labels like “OK” or “Cancel” without context.
+- Avoid stacking multiple sheets on top of each other.
+- Don’t interrupt the user’s workflow unnecessarily.
+
+## Accessibility support
+
+The `Sheet` component uses the native `dialog` element to provide a modal dialog which comes with browser-specific behavior. As a result, accessibility features may vary across different browsers.
+
+### Keyboard
+
+| Key / state | Function |
+| --- | --- |
+| `Tab`, `Shift-Tab` | Moves focus to the next (or previous) focusable element inside the dialog. Focus is trapped (browser behavior). |
+| `ESC` | Closes the dialog. |
+| `focus` on trigger element | The focus is returned to the trigger element after closing the dialog (browser behavior). |
+
+### ARIA enhancements
+
+#### External **ARIA** provided by the `aria` property:
+
+| ARIA | Usage |
+| --- | --- |
+| `aria-label` | Defines a string value that labels the dialog element. |
+| `role` | Defines the semantic of the dialog element (`dialog` or `alertdialog`). |
+
+#### Internal **ARIA** that is managed by the component:
+
+| ARIA | Usage |
+| --- | --- |
+| `aria-label="STRING"` | Defines the accessible name if no `aria` property is provided, uses the contents of the header slot and falls back to a fixed name. |
+
+## Development considerations
+
+Set `aria-haspopup` on the trigger so users know a dialog will open. Ensure the sheet has a meaningful title via the header slot or `aria` property.
+
+### Common do's and don'ts
+
+- **Do** use a semantic trigger (usually a button) with a meaningful accessible name.
+- **Do** set `aria-haspopup` through the trigger component `aria` prop when opening the sheet.
+- **Do** ensure a meaningful title/label is available via the header slot or `aria` property.
+- **Don't** add raw host-level ARIA attributes as a workaround.
+- **Don't** use unclear trigger copy like "Open" when the sheet purpose is not obvious.
+
+## API
+
+### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `aria` | `SheetAriaAttribute` | `undefined` | Sets ARIA attributes on the sheet dialog element for improved accessibility when the default `aria-label` is insufficient. |
+| `background` | `'canvas'` `'surface'` | `'canvas'` | Sets the background color of the sheet panel (`canvas` or `surface`). |
+| `disableBackdropClick` | `boolean` | `false` | When enabled, clicking the backdrop will not close the sheet. |
+| `dismissButton` | `boolean` | `true` | Shows a dismiss button in the sheet header so users can manually close it. |
+| `open` _(required)_ | `boolean` | `false` | Controls whether the sheet panel slides in from the bottom and is visible to the user. |
+
+### Events
+
+| Event | Type | Description |
+| --- | --- | --- |
+| `dismiss` | `CustomEvent<void>` | Emitted when the user dismisses the sheet via the close button, backdrop click, or Escape key. |
+| `motionHiddenEnd` | `CustomEvent<SheetMotionHiddenEndEventDetail>`<br>`TransitionEvent` | Emitted after the sheet's close transition has fully completed and the panel is hidden. |
+| `motionVisibleEnd` | `CustomEvent<SheetMotionVisibleEndEventDetail>`<br>`TransitionEvent` | Emitted after the sheet's open transition has fully completed and the panel is visible. |
+
+### 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 |
+| --- | --- | --- | --- |
+| `header` | no | — | Renders a header section above the content area. |
+| _(default)_ | no | — | Default slot for the main content. |
+
+### CSS Variables
+
+| CSS Variable | Default | Description |
+| --- | --- | --- |
+| `--ref-p-sheet-pt` | — | Exposes the internally used padding-top of the Sheet as read only CSS variable. When slotting e.g. a media container, this variable can be used to stretch the element to the top of the Sheet. |
+| `--ref-p-sheet-pb` | — | Exposes the internally used padding-bottom of the Sheet as read only CSS variable. When slotting e.g. a media container, this variable can be used to stretch the element to the bottom of the Sheet. |
+| `--ref-p-sheet-px` | — | Exposes the internally used padding-inline of the Sheet as read only CSS variable. When slotting e.g. a media container, this variable can be used to stretch the element to the full horizontal size of the Sheet. |
+
+## Examples
+
+| Example | When to use | File |
+| --- | --- | --- |
+| Default | Minimal default configuration. | [./examples/Default.ts](./examples/Default.ts) |

package/skill/references/components/p-spinner/examples/Color.ts

@@ -0,0 +1,16 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <p-text [style]="{'color': 'light-dark(mediumvioletred, deeppink)'}" color="inherit">
+        <p-spinner class="me-static-sm" color="inherit" [aria]="{'aria-label': 'Loading page content'}"></p-spinner>
+        Some text
+      </p-text>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

package/skill/references/components/p-spinner/examples/ColorCssVar.ts

@@ -0,0 +1,13 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <p-spinner class="[--p-spinner-color:deeppink] [--p-spinner-track-color:lightpink]" [aria]="{'aria-label': 'Loading page content'}"></p-spinner>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

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

@@ -0,0 +1,13 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <p-spinner [aria]="{'aria-label': 'Loading page content'}"></p-spinner>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

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

@@ -0,0 +1,13 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <p-spinner [size]="{'base': 'sm', 'l': '2xl'}" [aria]="{'aria-label': 'Loading page content'}"></p-spinner>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

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

@@ -0,0 +1,16 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <p-text class="text-[48px]" size="inherit">
+        <p-spinner class="me-static-sm" size="inherit" [aria]="{'aria-label': 'Loading page content'}"></p-spinner>
+        Some text
+      </p-text>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

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

@@ -0,0 +1,13 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <p-spinner class="[--p-spinner-size:48px]" [aria]="{'aria-label': 'Loading page content'}"></p-spinner>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

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.ts](./examples/Default.ts) |
+| Size via Prop | There are predefined sizes for the component available which should cover most use cases. | [./examples/Size.ts](./examples/Size.ts) |
+| 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.ts](./examples/SizeCssVar.ts) |
+| 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.ts](./examples/ResponsiveSize.ts) |
+| 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.ts](./examples/Color.ts) |
+| 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.ts](./examples/ColorCssVar.ts) |

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

@@ -0,0 +1,26 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <p-stepper-horizontal>
+        <p-stepper-horizontal-item state="complete">
+          Step 1
+        </p-stepper-horizontal-item>
+        <p-stepper-horizontal-item state="warning">
+          Step 2
+        </p-stepper-horizontal-item>
+        <p-stepper-horizontal-item state="current">
+          Step 3
+        </p-stepper-horizontal-item>
+        <p-stepper-horizontal-item>
+          Step 4
+        </p-stepper-horizontal-item>
+      </p-stepper-horizontal>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}