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

package/skills/pds-knowledge-angular/references/components/p-model-signature/p-model-signature.md

@@ -0,0 +1,62 @@
+# p-model-signature
+
+The `p-model-signature` component is purely visual and renders the different signatures of Porsche car models. It can be used to overlay background images or enhance cards and teasers to be more dynamic and recognizable.
+
+## Usage
+
+### Do:
+
+- Use signatures for emotional introduction and communication of model series.
+- Consider using model signatures only occasionally, for example, within the Link Tile component for a specific model line.
+- Use model signatures as a subtle, larger background watermark, paired with appropriate visualization of vehicle detail pages.
+- Use as a headline-like element on model series overview pages.
+
+### Don't:
+
+- Avoid including signatures for specific derivatives such as a Panamera 4 Sport Turismo
+- Platinum Edition or a 911 Targa 4S or in line with the text.
+- The model signature should have sufficient spacing from the text.
+- Avoid repeating the same model series signature within the interface.
+- For example, do not display the 911 signatures twice or more in a viewport.
+
+## Accessibility support
+
+This component does not include any special accessibility features.
+
+## API
+
+### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `color` | `'primary'` `'contrast-low'` `'contrast-medium'` `'contrast-high'` `'inherit'` | `'primary'` | Sets the fill color of the signature using PDS color tokens. |
+| `fetchPriority` | `'low'` `'high'` `'auto'` | `'auto'` | Sets the browser's fetch priority hint for the signature asset (`auto`, `high`, `low`). |
+| `lazy` | `boolean` | `false` | Defers loading the signature until it enters the viewport to improve initial page performance. |
+| `model` | `'718'` `'911'` `'boxster'` `'cayenne'` `'cayman'` `'gt3-rs'` `'gt3'` `'gts'` `'macan'` `'panamera'` `'taycan'` `'turbo-s'` `'turbo'` | `'911'` | Selects the Porsche model whose typographic signature SVG is displayed. |
+| `safeZone` | `boolean` | `true` | When enabled, adds invisible padding so all model signatures visually align to a consistent baseline. |
+| `size` | `'small'` `'inherit'` | `'small'` | Sets the display size of the signature using predefined PDS sizes. Use `inherit` with a CSS `width` or `height` on the host for custom sizing. |
+
+### Slots
+
+| Slot | Required | Allowed tag names | Description |
+| --- | --- | --- | --- |
+| _(default)_ | no | — | Default slot for an img or video tag when using the model-signature as a mask. |
+
+### CSS Variables
+
+| CSS Variable | Default | Description |
+| --- | --- | --- |
+| `--p-model-signature-width` | — | Overrides the width of the model signature. |
+| `--p-model-signature-height` | `auto` | Overrides the height of the model signature. |
+| `--p-model-signature-color` | — | Overrides the fill color of the model signature. Overrides the `color` property when set. |
+
+## Examples
+
+| Example | When to use | File |
+| --- | --- | --- |
+| Default | Minimal default configuration. | [./examples/Default.ts](./examples/Default.ts) |
+| Safe Zone | The `safe-zone` prop's default is `modelSignatureSafeZoneDefault`, which ensures a visual balance across all model signatures. | [./examples/SafeZone.ts](./examples/SafeZone.ts) |
+| Mask: Blend Mode | If `p-model-signature` should be blended with its background, the CSS property [mix-blend-mode](https://developer.mozilla.org/en-US/docs/Web/CSS/mix-blend-mode) can be used (`{{ blendMode }}` will produce the best results). | [./examples/MaskBlendMode.ts](./examples/MaskBlendMode.ts) |
+| Mask: Image | > **Experimental** > > The following example shows what is technically possible but has not yet been approved by the Porsche Brand Guide. | [./examples/MaskImage.ts](./examples/MaskImage.ts) |
+| Mask: Video | > **Experimental** > > The following example shows what is technically possible but has not yet been approved by the Porsche Brand Guide. | [./examples/MaskVideo.ts](./examples/MaskVideo.ts) |
+| Custom styling | The `p-model-signature` color can be changed by setting the `color` prop to `inherit` and applying some CSS `color`. | [./examples/CustomStyling.ts](./examples/CustomStyling.ts) |

package/skills/pds-knowledge-angular/references/components/p-multi-select/accessibility.md

@@ -0,0 +1,78 @@
+# p-multi-select accessibility integration examples
+
+## Integration examples
+
+### Prompt option used instead of a label
+
+#### ❌ Anti-pattern
+
+```html
+<p-multi-select name="features">
+  <p-multi-select-option value="">
+    Select features
+  </p-multi-select-option>
+  <p-multi-select-option value="sport">
+    Sport Chrono Package
+  </p-multi-select-option>
+</p-multi-select>
+```
+
+#### ✅ Recommended
+
+```html
+<p-multi-select label="Optional features" name="features" description="Select all features for your configuration.">
+  <p-multi-select-option value="sport">
+    Sport Chrono Package
+  </p-multi-select-option>
+  <p-multi-select-option value="audio">
+    BOSE Surround Sound
+  </p-multi-select-option>
+</p-multi-select>
+```
+
+### Hidden label without accessible name
+
+#### ❌ Anti-pattern
+
+```html
+<p-multi-select name="features" [hideLabel]="true">
+  <p-multi-select-option value="sport">
+    Sport Chrono Package
+  </p-multi-select-option>
+</p-multi-select>
+```
+
+#### ✅ Recommended
+
+```html
+<p-multi-select label="Optional features" name="features" [hideLabel]="true">
+  <p-multi-select-option value="sport">
+    Sport Chrono Package
+  </p-multi-select-option>
+</p-multi-select>
+```
+
+### Validation feedback via state and message API
+
+#### ❌ Anti-pattern
+
+```html
+<p-multi-select label="Optional features" name="features" [aria-invalid]="true" message="Required">
+  <p-multi-select-option value="sport">
+    Sport Chrono Package
+  </p-multi-select-option>
+</p-multi-select>
+```
+
+#### ✅ Recommended
+
+```html
+<p-multi-select label="Optional features" name="features" [required]="true" state="error" message="Select at least one feature to continue.">
+  <p-multi-select-option value="sport">
+    Sport Chrono Package
+  </p-multi-select-option>
+  <p-multi-select-option value="audio">
+    BOSE Surround Sound
+  </p-multi-select-option>
+</p-multi-select>
+```

package/skills/pds-knowledge-angular/references/components/p-multi-select/examples/AsyncFilter.ts

@@ -0,0 +1,149 @@
+import { ChangeDetectionStrategy, ChangeDetectorRef, Component } from '@angular/core';
+import {
+  type InputSearchInputEventDetail,
+  type MultiSelectChangeEventDetail,
+  type MultiSelectToggleEventDetail,
+  PMultiSelect,
+  PorscheDesignSystemModule,
+} from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+    <p-multi-select
+      name="async-search-select"
+      label="Async Search"
+      [value]="value"
+      (change)="onChange($event)"
+      (toggle)="onToggle($event)"
+    >
+      <p-input-search
+        slot="filter"
+        name="search"
+        [value]="searchValue"
+        [loading]="loading"
+        [clear]="true"
+        [indicator]="true"
+        [compact]="true"
+        [autoComplete]="'off'"
+        (input)="onInput($event)"
+        (blur)="$event.stopPropagation()"
+        (change)="$event.stopPropagation()"
+      ></p-input-search>
+
+      <!-- Initial skeleton loading -->
+      @if (initialLoading && !error) {
+        @for (_ of [1,2,3,4,5,6,7,8,9]; track $index) {
+          <div slot="options-status" class="skeleton h-[40px]"></div>
+        }
+      }
+
+      <!-- Options -->
+      @for (option of options; track option.value) {
+        <p-multi-select-option [value]="option.value">
+          {{ option.label }}
+        </p-multi-select-option>
+      }
+
+      <!-- No filter results -->
+      @if (!initialLoading && options.length === 0 && !error) {
+        <div
+          slot="options-status"
+          class="text-contrast-medium cursor-not-allowed py-static-sm px-[12px]"
+          role="alert"
+        >
+          <span aria-hidden="true">–</span>
+          <span class="sr-only">No results found</span>
+        </div>
+      }
+
+      <!-- Error state -->
+      @if (error) {
+        <div
+          slot="options-status"
+          class="flex gap-static-sm py-static-sm px-[12px]"
+          role="alert"
+        >
+          <p-icon name="information" color="error"></p-icon>
+          <span class="text-error">{{ error }}</span>
+        </div>
+      }
+    </p-multi-select>
+
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule],
+})
+export class ExampleComponent {
+  value?: PMultiSelect['value'] = [];
+  options: { value: string; label: string }[] = [];
+
+  searchValue = '';
+  initialLoading = false;
+  loading = false;
+  error: string | null = null;
+
+  private hasLoadedOnce = false;
+  private currentFetchId = 0;
+  private debounceTimer?: number;
+
+  constructor(private cdr: ChangeDetectorRef) {}
+
+  async fetchOptions(term?: string, isInitial = false) {
+    const fetchId = ++this.currentFetchId;
+    if (isInitial) this.initialLoading = true;
+    else this.loading = true;
+
+    this.cdr.markForCheck();
+
+    try {
+      const url = term
+        ? `https://jsonplaceholder.typicode.com/users?username_like=${term}`
+        : `https://jsonplaceholder.typicode.com/users`;
+
+      const res = await fetch(url);
+      const data: { id: number; name: string; username: string }[] = await res.json();
+
+      // Ignore stale results
+      if (fetchId !== this.currentFetchId) return;
+
+      this.options = data.map((user) => ({
+        value: user.id.toString(),
+        label: `${user.name} (${user.username})`,
+      }));
+
+      this.error = null;
+      this.hasLoadedOnce = true;
+    } catch (err) {
+      console.error('Failed to fetch options', err);
+      this.options = [];
+      this.error = 'Failed to load options';
+    } finally {
+      if (isInitial) this.initialLoading = false;
+      else this.loading = false;
+
+      this.cdr.markForCheck();
+    }
+  }
+
+  onInput(event: CustomEvent<InputSearchInputEventDetail>) {
+    const term = (event.target as HTMLInputElement).value;
+    this.searchValue = term;
+
+    if (this.debounceTimer) clearTimeout(this.debounceTimer);
+    this.debounceTimer = window.setTimeout(() => {
+      this.fetchOptions(term.trim() || undefined);
+    }, 400);
+  }
+
+  onChange(event: CustomEvent<MultiSelectChangeEventDetail>) {
+    this.value = (event.target as HTMLElement & { value: string[] }).value;
+  }
+
+  onToggle(event: CustomEvent<MultiSelectToggleEventDetail>) {
+    if (event.detail.open && !this.hasLoadedOnce) {
+      this.fetchOptions(undefined, true);
+    }
+  }
+}

package/skills/pds-knowledge-angular/references/components/p-multi-select/examples/Default.ts

@@ -0,0 +1,32 @@
+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="name" label="Some Label" description="Some description">
+        <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>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

package/skills/pds-knowledge-angular/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/skills/pds-knowledge-angular/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/skills/pds-knowledge-angular/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/skills/pds-knowledge-angular/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/skills/pds-knowledge-angular/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 {}