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

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

@@ -0,0 +1,54 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <p-scroller class="max-w-[600px] whitespace-nowrap">
+        <p-tag class="me-static-md" color="primary">
+          <button type="button">
+            Some tag content
+          </button>
+        </p-tag>
+        <p-tag class="me-static-md" color="notification-info-soft">
+          <button type="button">
+            Some tag content
+          </button>
+        </p-tag>
+        <p-tag class="me-static-md" color="notification-warning-soft">
+          <button type="button">
+            Some tag content
+          </button>
+        </p-tag>
+        <p-tag class="me-static-md" color="primary">
+          <button type="button">
+            Some tag content
+          </button>
+        </p-tag>
+        <p-tag class="me-static-md" color="notification-info-soft">
+          <button type="button">
+            Some tag content
+          </button>
+        </p-tag>
+        <p-tag class="me-static-md" color="notification-warning-soft">
+          <button type="button">
+            Some tag content
+          </button>
+        </p-tag>
+        <p-tag class="me-static-md" color="primary">
+          <button type="button">
+            Some tag content
+          </button>
+        </p-tag>
+        <p-tag color="notification-info-soft">
+          <button type="button">
+            Some tag content
+          </button>
+        </p-tag>
+      </p-scroller>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

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

@@ -0,0 +1,29 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <p-scroller class="max-w-[600px] whitespace-nowrap">
+        <p-tag-dismissible class="me-static-md">
+          Some tag content
+        </p-tag-dismissible>
+        <p-tag-dismissible class="me-static-md">
+          Some tag content
+        </p-tag-dismissible>
+        <p-tag-dismissible class="me-static-md">
+          Some tag content
+        </p-tag-dismissible>
+        <p-tag-dismissible class="me-static-md">
+          Some tag content
+        </p-tag-dismissible>
+        <p-tag-dismissible class="me-static-md">
+          Some tag content
+        </p-tag-dismissible>
+      </p-scroller>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

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

@@ -0,0 +1,43 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  styles: [
+    `
+      p-scroller > *:not(:last-child) {
+        margin-right: 1rem;
+      }
+
+      button {
+        margin: 0 1rem 1rem 0;
+      }
+    `,
+  ],
+  template: `
+    <div class="flex gap-fluid-sm">
+      <p-button type="button" (click)="onClick(0)" [compact]="true">Scroll to start</p-button>
+      <p-button type="button" (click)="onClick(220)" [compact]="true">Scroll to middle</p-button>
+      <p-button type="button" (click)="onClick(720)" [compact]="true">Scroll to end</p-button>
+    </div>
+    <div style="max-width: 400px; white-space: nowrap" class="mt-fluid-sm">
+      <p-scroller [scrollToPosition]="{scrollPosition, isSmooth}">
+        <p-tag-dismissible>START - some tag content</p-tag-dismissible>
+        <p-tag-dismissible>MIDDLE - some tag content</p-tag-dismissible>
+        <p-tag-dismissible>END - some tag content</p-tag-dismissible>
+      </p-scroller>
+    </div>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule],
+})
+export class ExampleComponent {
+  scrollPosition: number = 220;
+  isSmooth: boolean = false;
+
+  onClick = (scrollPosition: number) => {
+    this.scrollPosition = scrollPosition;
+    this.isSmooth = true;
+  };
+}

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.ts](./examples/Default.ts) |
+| Height | The height of `p-scroller` depends on the height of its content. | [./examples/Height.ts](./examples/Height.ts) |
+| Scroll to position | The `p-scroller` component provides the `scrollToPosition` property. | [./examples/ScrollToPosition.ts](./examples/ScrollToPosition.ts) |

package/skill/references/components/p-segmented-control/examples/Default.ts

@@ -0,0 +1,29 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <p-segmented-control label="Some Label" description="Some description">
+        <p-segmented-control-item value="1">
+          Option 1
+        </p-segmented-control-item>
+        <p-segmented-control-item value="2">
+          Option 2
+        </p-segmented-control-item>
+        <p-segmented-control-item value="3">
+          Option 3
+        </p-segmented-control-item>
+        <p-segmented-control-item value="4">
+          Option 4
+        </p-segmented-control-item>
+        <p-segmented-control-item value="5">
+          Option 5
+        </p-segmented-control-item>
+      </p-segmented-control>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

package/skill/references/components/p-segmented-control/examples/Form.ts

@@ -0,0 +1,37 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { FormControl, FormGroup, FormsModule, ReactiveFormsModule } from '@angular/forms';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+    <form [formGroup]="form" (ngSubmit)="onSubmit()" class="flex flex-col gap-fluid-sm">
+      <p-segmented-control formControlName="mySegmentedControl">
+        <p-segmented-control-item [value]="1">Option 1</p-segmented-control-item>
+        <p-segmented-control-item [value]="2">Option 2</p-segmented-control-item>
+        <p-segmented-control-item [value]="3">Option 3</p-segmented-control-item>
+        <p-segmented-control-item [value]="4">Option 4</p-segmented-control-item>
+        <p-segmented-control-item [value]="5">Option 5</p-segmented-control-item>
+      </p-segmented-control>
+      <div class="flex gap-fluid-sm">
+        <p-button type="submit">Submit</p-button>
+        <p-button type="reset">Reset</p-button>
+      </div>
+      <p-text>Last submitted data: {{ submittedValue }}</p-text>
+    </form>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule, FormsModule, ReactiveFormsModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {
+  form = new FormGroup({
+    mySegmentedControl: new FormControl<string | number | undefined>({ value: undefined, disabled: false }),
+  });
+
+  submittedValue: any = undefined;
+
+  onSubmit(): void {
+    this.submittedValue = JSON.stringify(this.form.value);
+  }
+}

package/skill/references/components/p-segmented-control/examples/Slots.ts

@@ -0,0 +1,57 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <p-segmented-control state="error">
+        <span slot="label" id="some-label-id">
+          Some label with a 
+          <a href="https://designsystem.porsche.com" class="underline">
+            link
+          </a>
+           and a "label-after" slot.
+        </span>
+        <p-popover slot="label-after">
+          Some Popover content with a 
+          <a href="https://designsystem.porsche.com" class="underline">
+            link
+          </a>
+          .
+        </p-popover>
+        <span slot="description" id="some-description-id">
+          Some description with a 
+          <a href="https://designsystem.porsche.com" class="underline">
+            link
+          </a>
+          .
+        </span>
+        <span slot="message" id="some-message-id">
+          Some error message with a 
+          <a href="https://designsystem.porsche.com" class="underline">
+            link
+          </a>
+          .
+        </span>
+        <p-segmented-control-item value="1">
+          Option 1
+        </p-segmented-control-item>
+        <p-segmented-control-item value="2">
+          Option 2
+        </p-segmented-control-item>
+        <p-segmented-control-item value="3">
+          Option 3
+        </p-segmented-control-item>
+        <p-segmented-control-item value="4">
+          Option 4
+        </p-segmented-control-item>
+        <p-segmented-control-item value="5">
+          Option 5
+        </p-segmented-control-item>
+      </p-segmented-control>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

package/skill/references/components/p-segmented-control/examples/WithLabels.ts

@@ -0,0 +1,29 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <p-segmented-control value="1">
+        <p-segmented-control-item value="1" label="Label">
+          Option 1
+        </p-segmented-control-item>
+        <p-segmented-control-item value="2" label="Label">
+          Option 2
+        </p-segmented-control-item>
+        <p-segmented-control-item value="3" label="Label">
+          Option 3
+        </p-segmented-control-item>
+        <p-segmented-control-item value="4" label="Label" [disabled]="true">
+          Option 4
+        </p-segmented-control-item>
+        <p-segmented-control-item value="5" label="Label">
+          Option 5
+        </p-segmented-control-item>
+      </p-segmented-control>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

package/skill/references/components/p-segmented-control/p-segmented-control.md

@@ -0,0 +1,162 @@
+# 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.
+
+## 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.ts](./examples/Default.ts) |
+| Form | The `p-segmented-control` can be integrated into a form in two ways: **controlled** or **uncontrolled**, depending on your needs. | [./examples/Form.ts](./examples/Form.ts) |
+| With Labels | Additional meta information can be displayed by setting a `label` on each child. | [./examples/WithLabels.ts](./examples/WithLabels.ts) |
+| Slots | Use named slots when `label`, `description` or `message` need markup such as a link. | [./examples/Slots.ts](./examples/Slots.ts) |