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

package/skill/references/components/p-multi-select/examples/Form.ts

@@ -0,0 +1,38 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { FormControl, FormGroup, FormsModule, ReactiveFormsModule, Validators } 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-multi-select formControlName="myMultiSelect" [label]="'Some Label'" >
+        <p-multi-select-option value="a">Option A</p-multi-select-option>
+        <p-multi-select-option value="b">Option B</p-multi-select-option>
+        <p-multi-select-option value="c">Option C</p-multi-select-option>
+        <p-multi-select-option value="d">Option D</p-multi-select-option>
+        <p-multi-select-option value="e">Option E</p-multi-select-option>
+        <p-multi-select-option value="f">Option F</p-multi-select-option>
+      </p-multi-select>
+      <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({
+    myMultiSelect: new FormControl<string[]>([]),
+  });
+
+  submittedValue: any = undefined;
+
+  onSubmit(): void {
+    this.submittedValue = JSON.stringify(this.form.value);
+  }
+}

package/skill/references/components/p-multi-select/examples/Optgroups.ts

@@ -0,0 +1,45 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <p-multi-select name="options" label="Some Label">
+        <p-optgroup label="Some optgroup label 1">
+          <p-multi-select-option value="a">
+            Option A
+          </p-multi-select-option>
+          <p-multi-select-option value="b">
+            Option B
+          </p-multi-select-option>
+          <p-multi-select-option value="c">
+            Option C
+          </p-multi-select-option>
+          <p-multi-select-option value="d">
+            Option D
+          </p-multi-select-option>
+          <p-multi-select-option value="e">
+            Option E
+          </p-multi-select-option>
+          <p-multi-select-option value="f">
+            Option F
+          </p-multi-select-option>
+        </p-optgroup>
+        <p-optgroup label="Some optgroup label 2">
+          <p-multi-select-option value="g">
+            Option G
+          </p-multi-select-option>
+          <p-multi-select-option value="h">
+            Option H
+          </p-multi-select-option>
+          <p-multi-select-option value="i">
+            Option I
+          </p-multi-select-option>
+        </p-optgroup>
+      </p-multi-select>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

package/skill/references/components/p-multi-select/examples/SelectedSlot.ts

@@ -0,0 +1,103 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import {
+  type MultiSelectChangeEventDetail,
+  PMultiSelect,
+  PorscheDesignSystemModule,
+} from '@porsche-design-system/components-angular';
+
+type Option = { value: string; label: string; description: string; tags: string[]; imgSrc: string };
+
+const optionsData: Option[] = [
+  {
+    value: '718',
+    label: '718',
+    description: 'Präziser Sportwagen mit Mittelmotor',
+    tags: ['Benzin'],
+    imgSrc: 'assets/718.png',
+  },
+  {
+    value: '911',
+    label: '911',
+    description: 'Ikonischer Sportwagen mit Heckmotor',
+    tags: ['Benzin'],
+    imgSrc: 'assets/911.png',
+  },
+  {
+    value: 'taycan',
+    label: 'Taycan',
+    description: 'Elektrischer Sportwagen',
+    tags: ['Elektro'],
+    imgSrc: 'assets/taycan.png',
+  },
+  {
+    value: 'macan',
+    label: 'Macan',
+    tags: ['Elektro'],
+    description: 'Sportlicher Kompakt-SUV',
+    imgSrc: 'assets/macan.png',
+  },
+  {
+    value: 'cayenne',
+    label: 'Cayenne',
+    tags: ['Hybrid', 'Benzin'],
+    description: 'Vielseitiger SUV',
+    imgSrc: 'assets/cayenne.png',
+  },
+  {
+    value: 'panamera',
+    label: 'Panamera',
+    tags: ['Hybrid', 'Benzin'],
+    description: 'Luxuslimousine mit hohem Komfort',
+    imgSrc: 'assets/panamera.png',
+  },
+];
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+    <p-multi-select
+      name="selected-slot-select"
+      label="Selected Slot"
+      [value]="value"
+      (change)="onChange($event)"
+    >
+    <span slot="selected" class="h-full flex items-center">
+      <span class="truncate">{{ selectedLabels }}</span>
+    </span>
+      @for (option of options; track option.value) {
+      <p-multi-select-option [value]="option.value">
+        <div class="w-full flex gap-fluid-sm">
+          <img [src]="option.imgSrc" alt="" class="h-[34px] w-auto self-center" />
+          <div class="flex flex-col justify-center flex-1 min-w-0">
+            <p class="prose-text-sm m-0">{{ option.label }}</p>
+            <p class="prose-text-2xs m-0">{{ option.description }}</p>
+          </div>
+          <div class="self-center flex gap-fluid-sm">
+            @for (tag of option.tags; track tag) {
+              <p-tag color="info-soft" [compact]="true">{{ tag }}</p-tag>
+            }
+          </div>
+        </div>
+      </p-multi-select-option>
+      }
+    </p-multi-select>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule],
+})
+export class ExampleComponent {
+  value: PMultiSelect['value'] = [];
+  options: Option[] = optionsData;
+  selectedOptions: Option[] = [];
+
+  get selectedLabels(): string {
+    return this.selectedOptions.map((option) => option.label).join(', ');
+  }
+
+  onChange(event: CustomEvent<MultiSelectChangeEventDetail>) {
+    const { value } = event.detail;
+    this.value = value;
+    this.selectedOptions = this.options.filter((option) => (value as string[]).includes(option.value));
+  }
+}

package/skill/references/components/p-multi-select/examples/SetValue.ts

@@ -0,0 +1,76 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import {
+  MultiSelectChangeEventDetail,
+  type PMultiSelectProps,
+  PorscheDesignSystemModule,
+} from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+  <div class="flex flex-col gap-fluid-sm">
+    <p-input-text
+      label="Value:"
+      name="input-value"
+      [value]="inputValue"
+      (input)="onChangeInput($event)"
+      placeholder="e.g. 1,2"
+    ></p-input-text>
+    <div class="flex gap-fluid-sm">
+      <p-button type="button" (click)="onSetValue()" [compact]="true">Set Value</p-button>
+      <p-button type="button" (click)="onResetValue()" [compact]="true">Reset value</p-button>
+    </div>
+    <p-multi-select name="options" label="Some Label" [value]="selectedValues" (change)="onChange($event)">
+      @for (idx of optionIndices; track idx) {
+        <p-multi-select-option [value]="(idx + 1).toString()"
+          >Option {{ idx + 1 }}</p-multi-select-option
+          >
+        }
+      </p-multi-select>
+      <div class="flex gap-fluid-sm">  
+        <p-button type="button" (click)="onAddOption()" [compact]="true">Add option</p-button>
+        <p-button type="button" (click)="onRemoveOption()" [compact]="true">Remove last option</p-button>
+      </div>
+    </div>
+    `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule],
+})
+export class ExampleComponent {
+  selectedValues: PMultiSelectProps['value'] = [];
+  inputValue: string = '';
+  optionCount: number = 3;
+
+  get optionIndices(): number[] {
+    return [...Array(this.optionCount).keys()];
+  }
+
+  onChangeInput(e: Event) {
+    this.inputValue = (e.target as HTMLInputElement).value;
+  }
+
+  onSetValue() {
+    this.selectedValues = this.inputValue.split(',');
+  }
+
+  onResetValue() {
+    this.selectedValues = [];
+    this.inputValue = '';
+  }
+
+  onChange(e: CustomEvent<MultiSelectChangeEventDetail>) {
+    this.selectedValues = e.detail.value;
+    this.inputValue = e.detail.value.join(',');
+  }
+
+  onAddOption() {
+    this.optionCount += 1;
+  }
+
+  onRemoveOption() {
+    if (this.optionCount > 0) {
+      this.optionCount -= 1;
+    }
+  }
+}

package/skill/references/components/p-multi-select/examples/Slots.ts

@@ -0,0 +1,51 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <p-multi-select name="options" 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-multi-select-option value="a">
+          Option A
+        </p-multi-select-option>
+        <p-multi-select-option value="b">
+          Option B
+        </p-multi-select-option>
+        <p-multi-select-option value="c">
+          Option C
+        </p-multi-select-option>
+      </p-multi-select>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

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

@@ -0,0 +1,197 @@
+# p-multi-select
+
+The `p-multi-select` component is a versatile custom form element that facilitates the selection of multiple options.
+
+Many of the properties closely resemble those found in the [select](../p-select/p-select.md) and other form components (e.g. `label`, `description`, `state`, `message`, `hideLabel`, `disabled`, `required` & `dropdownDirection`). The `p-multi-select` offers a search field by default. When the user types in a search string, the options are reduced by matching the options text.
+
+Options are slotted using the `p-multi-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-multi-select` component ([More Info](./p-multi-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.
+
+**Hint:** The `p-multi-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:
+
+- Use to search and select one or more options from a list.
+- Use to trigger an action based on a selected option or options.
+- Use with label for better accessibility whenever possible.
+- Use descriptive label text for screen readers when label hidden.
+- Use without label only if the context clearly describes what the component is to be used for and no further explanation is required.
+- Use description text to provide further information that is helpful for the user.
+- Use without a preselection (mandatory field) by default when no other data is available.
+- Use without a preselection (optional field) to make it possible to go back to an empty default.
+- Use with a preselection (mandatory field) if you know a specific selection is desired by the user or a previous step requires a selection or in case of a predictive journey.
+- Use as a mandatory field when a selection of one or more options is necessary to proceed.
+- Use 'dropdown direction' to adjust the flyout's direction to improve the experience.
+- Use 'validation states' error or success to give feedback on the selection.
+- Use common sort order for menu items (frequency of use, alpha or numeric).
+
+### Don't:
+
+- Don't use very long option texts.
+- Don’t use it for less than 6 options (otherwise use Checkboxes).
+- Don’t exceed maximum width so the option labels turn multiline.
+- Don't use the same option value twice.
+- Don't use the same option text twice.
+
+## 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. |
+
+#### 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` | 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-multiselectable="true"` | Indicates that more than one item from the current selectable descendants can be selected. |
+| `aria-autocomplete="list"` | Indicates that user input effects results of listbox. |
+| `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.
+- **Don't** use a prompt option or adjacent text as a substitute for a field label.
+- **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 a more compact layout. |
+| `description` | `string` | `''` | Sets a supplementary description displayed below the label to provide additional context. |
+| `disabled` | `boolean` | `false` | Disables the multi-select, preventing all interaction. Selected values are not submitted with the form. |
+| `dropdownDirection` | `'down'` `'up'` `'auto'` | `'auto'` | Controls whether the dropdown opens upward (`up`) or downward (`down`), or decides automatically (`auto`). |
+| `form` | `string` | `undefined` | Associates the multi-select with a form element by its ID when not directly nested inside it. |
+| `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 multi-select control. |
+| `message` | `string` | `''` | Sets the validation feedback message displayed below the control when `state` is `success` or `error`. |
+| `name` _(required)_ | `string` | `undefined` | Sets the name submitted with the form data to identify the selected values on the server. |
+| `required` | `boolean` | `false` | Marks the multi-select as required — form submission is blocked unless at least one option is selected. |
+| `state` | `'none'` `'error'` `'success'` | `'none'` | Sets the validation state, controlling the visual appearance and style of the feedback message (`none`, `success`, `error`). |
+| `value` | `'array(AllowedTypes.string)'` `'array(AllowedTypes.number)'` `'null'` | `[]` | The selected values. Matches options strictly by type and value, meaning a string value only matches options whose value is the same string, a number value only matches options whose value is the same number. Pass null or [] to clear the selection. 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 number-typed options. This limitation only applies to native form state restoration; in controlled forms (where the consumer manages value directly via the change event), number[] types are preserved end-to-end. |
+
+### Events
+
+| Event | Type | Description |
+| --- | --- | --- |
+| `blur` | `CustomEvent<void>` | Emitted when the multi-select loses focus. |
+| `change` | `CustomEvent<MultiSelectChangeEventDetail>`<br>`{ name: string; value: string[] | number[] }` | Emitted when the user selects or deselects an option, with the updated array of values in the event detail. |
+| `toggle` | `CustomEvent<MultiSelectToggleEventDetail>`<br>`{ open: boolean }` | Emitted when the dropdown opens or closes, with the new open 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 options display in the button area. |
+| _(default)_ | no | — | Default slot for the p-multi-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-multi-select` can be integrated into a form in two ways: **controlled** or **uncontrolled**, depending on your needs. | [./examples/Form.ts](./examples/Form.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-multi-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-multi-select` component automatically filters options based on user input. | [./examples/AsyncFilter.ts](./examples/AsyncFilter.ts) |
+| Custom option rendering | By default, `p-multi-select-option` only allows `#text` nodes. | [./examples/SelectedSlot.ts](./examples/SelectedSlot.ts) |

package/skill/references/components/p-pagination/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-pagination [totalItemsCount]="500" [itemsPerPage]="25" [activePage]="1"></p-pagination>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

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

@@ -0,0 +1,83 @@
+# p-pagination
+
+The `p-pagination` component divides large content sets into pages and should be used when all items cannot be displayed at once.
+
+To adapt the pagination to the specific viewport context, the amount of displayed page items varies between either `7` (desktop/tablet) or `5` (mobile). The components handles responsive viewport sizing by default.
+
+## Usage
+
+### Do:
+
+- Use when splitting large content into multiple pages.
+- Use to provide information on the number of pages available.
+- Use to show the current page position.
+- Use pagination to allow the user to navigate between the pages.
+- Display an ellipsis ("...") for a range of pages if there are at least 6 or 8 pages.
+- Place the pagination centered beneath the related content.
+
+### Don't:
+
+- Don't use unnecessarily for small amounts of content.
+- Don't use without providing information on the total number of pages available.
+- Don't use without showing the current page position.
+- Don't use without the option for the user to navigate between pages.
+- Don't place the pagination in an unrelated or confusing position.
+
+## Accessibility support
+
+### Keyboard
+
+| Key / state | Function |
+| --- | --- |
+| `Tab`, `Shift-Tab` | Moves focus to the next (or previous) focusable element. |
+| `Enter`, `Space` | Activates the item. |
+
+### ARIA enhancements
+
+#### Internal **ARIA** that is managed by the component:
+
+| ARIA | Usage |
+| --- | --- |
+| `aria-current` | Exposes the current state of the item. |
+
+#### External **ARIA** provided by the `intl` property:
+
+| ARIA | Usage |
+| --- | --- |
+| `aria-label` | Defines a string value that labels the navigation and interactive elements. |
+
+## Development considerations
+
+### Common do's and don'ts
+
+- **Do** localize `intl` strings so navigation labels match the page language.
+- **Do** keep prev/next and page button labels specific enough to identify the pagination control.
+- **Don't** rely on default English `intl` strings on localized pages.
+
+## API
+
+### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `activePage` | `number` | `1` | Sets the one-based index of the currently active page; update this prop to navigate programmatically. |
+| `intl` | `PaginationInternationalization` | `{"root":"Pagination","prev":"Previous page","next":"Next page","page":"Page"}` | Overrides the default ARIA label strings used for the previous, next, and page number buttons to support localisation. |
+| `itemsPerPage` _(required)_ | `number` | `1` | Sets the number of items displayed per page, used together with `totalItemsCount` to compute the page count. |
+| `showLastPage` | `boolean` | `true` | Shows or hides the button that jumps directly to the last page of the pagination. |
+| `totalItemsCount` _(required)_ | `number` | `1` | Sets the total number of items in the dataset, used to calculate the number of pages. |
+
+### Events
+
+| Event | Type | Description |
+| --- | --- | --- |
+| `update` | `CustomEvent<PaginationUpdateEventDetail>`<br>`{ page: number; previousPage: number }` | Emitted when the user navigates to a different page, carrying the new `activePage` index in the event detail. |
+
+### Controlled properties
+
+- `activePage` — a controlled prop, but the component also updates it internally. Listen for the `update` event to observe changes; you do not have to write the value back.
+
+## Examples
+
+| Example | When to use | File |
+| --- | --- | --- |
+| Default | Minimal default configuration. | [./examples/Default.ts](./examples/Default.ts) |

package/skill/references/components/p-pin-code/examples/CopyPaste.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-pin-code label="Some label"></p-pin-code>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

package/skill/references/components/p-pin-code/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-pin-code label="Some label"></p-pin-code>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}