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

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

@@ -0,0 +1,107 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import {
+  type PStepperHorizontalItemProps,
+  PorscheDesignSystemModule,
+  StepperHorizontalUpdateEventDetail,
+} from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+  <div class="flex flex-col gap-fluid-sm">
+    <p-stepper-horizontal (update)="onUpdate($event)">
+      @for (step of steps; track step) {
+        <p-stepper-horizontal-item [state]="step.state">
+          {{ step.name }}
+        </p-stepper-horizontal-item>
+      }
+    </p-stepper-horizontal>
+
+    @for (content of stepContent; track content; let i = $index) {
+      @if (getActiveStepIndex(steps) === i) {
+        <p-text>{{ content }}</p-text>
+      }
+    }
+
+    <div class="flex gap-fluid-sm">
+      <p-button
+        type="button"
+        [icon]="'arrow-head-left'"
+        [variant]="'secondary'"
+        [disabled]="getActiveStepIndex(steps) === 0"
+        (click)="onNextPrevStep('prev')"
+      >
+        Previous Step
+      </p-button>
+
+      <p-button
+        type="button"
+        [variant]="'primary'"
+        [disabled]="getActiveStepIndex(steps) === steps.length - 1"
+        (click)="onNextPrevStep('next')"
+        >
+        Next Step
+      </p-button>
+    </div>
+  </div>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule],
+})
+export class ExampleComponent {
+  steps: StepperHorizontalItemProps[] = [
+    {
+      state: 'current',
+      name: 'Enter personal details',
+    },
+    {
+      name: 'Confirm e-mail',
+    },
+    {
+      name: 'Set password',
+    },
+  ];
+
+  stepContent: string[] = [
+    'A form with personal details could be displayed here.',
+    'A form with a verification code input field could be displayed here.',
+    'A form with a password input field could be displayed here.',
+  ];
+
+  getActiveStepIndex(steps: StepperHorizontalItemProps[]): number {
+    return steps.findIndex((step) => step.state === 'current');
+  }
+
+  onNextPrevStep(direction: 'next' | 'prev'): void {
+    const newState = [...this.steps];
+    const activeStepIndex = this.getActiveStepIndex(newState);
+
+    if (direction === 'next') {
+      newState[activeStepIndex].state = 'complete';
+      newState[activeStepIndex + 1].state = 'current';
+    } else {
+      delete newState[activeStepIndex].state;
+      newState[activeStepIndex - 1].state = 'current';
+    }
+
+    this.steps = newState;
+  }
+
+  onUpdate(e: CustomEvent<StepperHorizontalUpdateEventDetail>): void {
+    const { activeStepIndex } = e.detail;
+
+    const newState = [...this.steps];
+    for (let i = activeStepIndex + 1; i < newState.length; i++) {
+      // reset step state when going back via stepper horizontal item click
+      delete newState[i].state;
+    }
+    newState[activeStepIndex].state = 'current';
+
+    this.steps = newState;
+  }
+}
+
+type StepperHorizontalItemProps = PStepperHorizontalItemProps & {
+  name: string;
+};

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

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

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

@@ -0,0 +1,21 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule, type SwitchUpdateEventDetail } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <p-switch [checked]="checked" (update)="onUpdate($event)">
+        Some label
+      </p-switch>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {
+  checked = false;
+
+  onUpdate(e: CustomEvent<SwitchUpdateEventDetail>) {
+    this.checked = e.detail.checked;
+  }
+}

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

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

package/skill/references/components/p-table/examples/Advanced.ts

@@ -0,0 +1,162 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule, TableUpdateEventDetail } from '@porsche-design-system/components-angular';
+
+type HeadAdvanced = {
+  id: string;
+  name: string;
+  hideLabel: boolean;
+  active?: boolean;
+  direction?: 'asc' | 'desc';
+};
+
+const headAdvanced: HeadAdvanced[] = [
+  { name: 'Model', id: 'model' } as HeadAdvanced,
+  { name: 'Interest', id: 'interest' } as HeadAdvanced,
+  { name: 'VIN', id: 'vin' } as HeadAdvanced,
+  { name: 'Purchase Intention', id: 'purchaseIntention' } as HeadAdvanced,
+  { name: 'Status', id: 'status' } as HeadAdvanced,
+  { name: 'Comment', id: 'comment' } as HeadAdvanced,
+  { name: 'Lead ID', id: 'leadId' } as HeadAdvanced,
+  { name: 'Select Wrapper', id: 'selectWrapper' } as HeadAdvanced,
+  { name: 'Select', id: 'select' } as HeadAdvanced,
+  { name: 'Multi-Select', id: 'multiSelect' } as HeadAdvanced,
+  { name: 'Action', id: 'action', hideLabel: true } as HeadAdvanced,
+].map((item, i) => ({
+  ...item,
+  ...(i > 0 &&
+    i < 7 &&
+    i !== 5 && {
+      active: i === 1,
+      direction: 'asc',
+    }),
+}));
+
+type DataAdvanced = {
+  imageUrl: string;
+  model: string;
+  date: string;
+  interest: string;
+  vin: string;
+  purchaseIntention: string;
+  status: string;
+  comment: string;
+  leadId: string;
+};
+
+const dataAdvanced: DataAdvanced[] = [
+  {
+    imageUrl: 'assets/718.png',
+    model: '718',
+    date: '23.06.2021',
+    interest: 'New Car',
+    vin: '1FM5K7F84FGB16304',
+    purchaseIntention: '08/2021',
+    status: 'Won',
+    comment: '-',
+    leadId: '0000824402',
+  },
+  {
+    imageUrl: 'assets/panamera.png',
+    model: 'Panamera',
+    date: '19.06.2021',
+    interest: 'New Car',
+    vin: '2GCEC13T141374801',
+    purchaseIntention: '11/2021',
+    status: 'Lost',
+    comment: 'Some multiline text and a column with a min width.',
+    leadId: '0000824409',
+  },
+  {
+    imageUrl: 'assets/911.png',
+    model: '911',
+    date: '19.05.2021',
+    interest: 'Used Car',
+    vin: '5GAKVCKD8EJ335750',
+    purchaseIntention: '09/2021',
+    status: 'Won',
+    comment: '-',
+    leadId: '0000824408',
+  },
+  {
+    imageUrl: 'assets/macan.png',
+    model: 'Macan',
+    date: '10.05.2021',
+    interest: 'Used Car',
+    vin: '1FMPU17L83LC09302',
+    purchaseIntention: '07/2021',
+    status: 'Lost',
+    comment: '-',
+    leadId: '0000824407',
+  },
+  {
+    imageUrl: 'assets/taycan.png',
+    model: 'Taycan',
+    date: '03.05.2021',
+    interest: 'New Car',
+    vin: 'JN1BY1AR3BM375187',
+    purchaseIntention: '05/2021',
+    status: 'Won',
+    comment: '-',
+    leadId: '0000824406',
+  },
+];
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+    <p-table (update)="onUpdate($event)">
+      <p-heading slot="caption" size="large" tag="h3">Some visual caption</p-heading>
+      <p-table-head>
+        <p-table-head-row>
+          @for (item of head; track item) {
+            <p-table-head-cell [sort]="item" [hideLabel]="item.hideLabel">
+              {{ item.name }}
+            </p-table-head-cell>
+          }
+        </p-table-head-row>
+      </p-table-head>
+      <p-table-body>
+        @for (item of data; track item) {
+          <p-table-row>
+            <p-table-cell>
+              <div style="display: flex;">
+                <img src="{{ item.imageUrl }}" width="80" height="45" style="margin-right: .5rem; object-fit: contain; max-width: none;" alt="" />
+                <div>
+                  <p-text weight="semi-bold">{{ item.model }}</p-text>
+                  <p-text size="x-small">{{ item.date }}</p-text>
+                </div>
+              </div>
+            </p-table-cell>
+            <p-table-cell>{{ item.interest }}</p-table-cell>
+            <p-table-cell>
+              <a href="https://porsche.com">{{ item.vin }}</a>
+            </p-table-cell>
+            <p-table-cell>{{ item.purchaseIntention }}</p-table-cell>
+            <p-table-cell>{{ item.status }}</p-table-cell>
+            <p-table-cell [multiline]="true" style="min-width: 10rem;">{{ item.comment }}</p-table-cell>
+            <p-table-cell>{{ item.leadId }}</p-table-cell>
+            <p-table-cell>
+              <p-button-pure icon="edit" style="padding: .5rem">Edit</p-button-pure>
+              <p-button-pure icon="delete" style="padding: .5rem">Delete</p-button-pure>
+            </p-table-cell>
+          </p-table-row>
+        }
+      </p-table-body>
+    </p-table>
+    `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule],
+})
+export class ExampleComponent {
+  public head = headAdvanced;
+  public data = dataAdvanced;
+
+  onUpdate(e: CustomEvent<TableUpdateEventDetail>): void {
+    const { id, direction } = e.detail as TableUpdateEventDetail & { id: keyof DataAdvanced };
+    this.head = this.head.map((item) => ({ ...item, active: false, ...(item.id === id && e.detail) }));
+    this.data = [...this.data].sort((a, b) =>
+      direction === 'asc' ? a[id].localeCompare(b[id]) : b[id].localeCompare(a[id])
+    );
+  }
+}

package/skill/references/components/p-table/examples/CaptionProperty.ts

@@ -0,0 +1,40 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <p-table caption="Some caption">
+        <p-table-head>
+          <p-table-head-row>
+            <p-table-head-cell>
+              Column 1
+            </p-table-head-cell>
+            <p-table-head-cell>
+              Column 2
+            </p-table-head-cell>
+            <p-table-head-cell>
+              Column 3
+            </p-table-head-cell>
+          </p-table-head-row>
+        </p-table-head>
+        <p-table-body>
+          <p-table-row>
+            <p-table-cell>
+              Cell 1
+            </p-table-cell>
+            <p-table-cell>
+              Cell 2
+            </p-table-cell>
+            <p-table-cell>
+              Cell 3
+            </p-table-cell>
+          </p-table-row>
+        </p-table-body>
+      </p-table>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

package/skill/references/components/p-table/examples/CaptionSlot.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',
+  template: `
+      <p-table>
+        <p-heading slot="caption" size="large" tag="h3">
+          Some slotted caption
+        </p-heading>
+        <p-table-head>
+          <p-table-head-row>
+            <p-table-head-cell>
+              Column 1
+            </p-table-head-cell>
+            <p-table-head-cell>
+              Column 2
+            </p-table-head-cell>
+            <p-table-head-cell>
+              Column 3
+            </p-table-head-cell>
+          </p-table-head-row>
+        </p-table-head>
+        <p-table-body>
+          <p-table-row>
+            <p-table-cell>
+              Cell 1
+            </p-table-cell>
+            <p-table-cell>
+              Cell 2
+            </p-table-cell>
+            <p-table-cell>
+              Cell 3
+            </p-table-cell>
+          </p-table-row>
+        </p-table-body>
+      </p-table>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}