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

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

@@ -0,0 +1,120 @@
+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>
+              Model
+            </p-table-head-cell>
+            <p-table-head-cell>
+              Date
+            </p-table-head-cell>
+            <p-table-head-cell>
+              Purchase Intention
+            </p-table-head-cell>
+            <p-table-head-cell>
+              Status
+            </p-table-head-cell>
+            <p-table-head-cell>
+              Lead ID
+            </p-table-head-cell>
+          </p-table-head-row>
+        </p-table-head>
+        <p-table-body>
+          <p-table-row>
+            <p-table-cell>
+              718 Cayman
+            </p-table-cell>
+            <p-table-cell>
+              23.06.2021
+            </p-table-cell>
+            <p-table-cell>
+              New Car
+            </p-table-cell>
+            <p-table-cell>
+              Won
+            </p-table-cell>
+            <p-table-cell>
+              0000824402
+            </p-table-cell>
+          </p-table-row>
+          <p-table-row>
+            <p-table-cell>
+              Panamera 4S
+            </p-table-cell>
+            <p-table-cell>
+              19.06.2021
+            </p-table-cell>
+            <p-table-cell>
+              New Car
+            </p-table-cell>
+            <p-table-cell>
+              Lost
+            </p-table-cell>
+            <p-table-cell>
+              0000824409
+            </p-table-cell>
+          </p-table-row>
+          <p-table-row>
+            <p-table-cell>
+              911 Carrera S
+            </p-table-cell>
+            <p-table-cell>
+              19.05.2021
+            </p-table-cell>
+            <p-table-cell>
+              Used Car
+            </p-table-cell>
+            <p-table-cell>
+              Won
+            </p-table-cell>
+            <p-table-cell>
+              0000824408
+            </p-table-cell>
+          </p-table-row>
+          <p-table-row>
+            <p-table-cell>
+              Macan Turbo
+            </p-table-cell>
+            <p-table-cell>
+              10.05.2021
+            </p-table-cell>
+            <p-table-cell>
+              Used Car
+            </p-table-cell>
+            <p-table-cell>
+              Lost
+            </p-table-cell>
+            <p-table-cell>
+              0000824407
+            </p-table-cell>
+          </p-table-row>
+          <p-table-row>
+            <p-table-cell>
+              Taycan
+            </p-table-cell>
+            <p-table-cell>
+              03.05.2021
+            </p-table-cell>
+            <p-table-cell>
+              New Car
+            </p-table-cell>
+            <p-table-cell>
+              Won
+            </p-table-cell>
+            <p-table-cell>
+              0000824406
+            </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/HideLabel.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 [hideLabel]="true">
+              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/LayoutFixed.ts

@@ -0,0 +1,53 @@
+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" layout="fixed">
+        <p-table-head>
+          <p-table-head-row>
+            <p-table-head-cell class="w-[50%] max-w-[50%]">
+              Column 1 (50%)
+            </p-table-head-cell>
+            <p-table-head-cell class="w-[150px] max-w-[150px]">
+              Column 2 (150px)
+            </p-table-head-cell>
+            <p-table-head-cell>
+              Column 3 (auto)
+            </p-table-head-cell>
+          </p-table-head-row>
+        </p-table-head>
+        <p-table-body>
+          <p-table-row>
+            <p-table-cell class="w-[50%] max-w-[50%]">
+              Cell 1
+            </p-table-cell>
+            <p-table-cell class="w-[150px] max-w-[150px]">
+              Cell 2
+            </p-table-cell>
+            <p-table-cell>
+              Cell 3
+            </p-table-cell>
+          </p-table-row>
+          <p-table-row>
+            <p-table-cell class="w-[50%] max-w-[50%]">
+              Cell 1
+            </p-table-cell>
+            <p-table-cell class="w-[150px] max-w-[150px]">
+              <p-text [ellipsis]="true" title="Cell 2 with more content">
+                Cell 2 with more content
+              </p-text>
+            </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/Sorting.ts

@@ -0,0 +1,79 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule, TableUpdateEventDetail } from '@porsche-design-system/components-angular';
+
+type HeadSorting = {
+  id: string;
+  name: string;
+  active?: boolean;
+  direction?: 'asc' | 'desc';
+};
+
+const headSorting: HeadSorting[] = [
+  { name: 'Column 1', id: 'col1' } as HeadSorting,
+  { name: 'Column 2', id: 'col2' } as HeadSorting,
+  { name: 'Column 3', id: 'col3' } as HeadSorting,
+].map((item, i) => ({
+  ...item,
+  active: i === 1,
+  direction: 'asc',
+}));
+
+type DataSorting = {
+  col1: string;
+  col2: string;
+  col3: string;
+};
+
+const dataSorting: DataSorting[] = [
+  {
+    col1: 'Name A',
+    col2: '9',
+    col3: '01.06.2021',
+  },
+  {
+    col1: 'Name Z',
+    col2: '1',
+    col3: '24.06.2021',
+  },
+];
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+    <p-table caption="Some caption" (update)="onUpdate($event)">
+      <p-table-head>
+        <p-table-head-row>
+          @for (item of head; track item) {
+            <p-table-head-cell [sort]="item">
+              {{ 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>{{ item.col1 }}</p-table-cell>
+            <p-table-cell>{{ item.col2 }}</p-table-cell>
+            <p-table-cell>{{ item.col3 }}</p-table-cell>
+          </p-table-row>
+        }
+      </p-table-body>
+    </p-table>
+    `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule],
+})
+export class ExampleComponent {
+  public head = headSorting;
+  public data = dataSorting;
+
+  onUpdate(e: CustomEvent<TableUpdateEventDetail>): void {
+    const { id, direction } = e.detail as TableUpdateEventDetail & { id: keyof DataSorting };
+    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/p-table.md

@@ -0,0 +1,189 @@
+# p-table
+
+The `p-table` component displays tabular data and offers column-wise sorting options. It combines a consistent appearance together with great accessibility while not having restrictions regarding its content. Therefore, it can be used for plain text but also rich content like images, form elements and buttons.
+
+It is a controlled component. This means it does not contain any internal state, and you got full control over its behavior.
+
+## Usage
+
+### Do:
+
+- Use to display and compare structured data in rows and columns.
+- Use as a tool to query consume and navigate to specific data.
+- Use if there are at least two or more columns of data parameters.
+- Ensure that the column headers are relevant to the data it represents and are succinct.
+- Include rich content in the cell data to support the specific requirements of the application use cases.
+- Enable sorting of columns in ascending or descending order with an arrow icon to indicate the order direction.
+- Ensure that the table is responsive and stretches to the full available width.
+- Include a table caption describing the contents of the table for accessibility
+- Use the built-in scroller for horizontal scrolling on mobile viewports.
+
+### Don't:
+
+- Don't use for non-structured data or data that can be presented in a simpler format.
+- Don't overuse or clutter cell data with unnecessary content.
+- Don't neglect to include a table caption for accessibility purposes.
+
+## Accessibility support
+
+### Keyboard
+
+| Key / state | Function |
+| --- | --- |
+| `Tab`, `Shift-Tab` | Moves focus to the next (or previous) sort button. |
+| `Enter`, `Space` | Changes sorting direction. |
+
+### ARIA enhancements
+
+#### Internal **ARIA** that is managed by the component:
+
+| ARIA | Usage |
+| --- | --- |
+| `aria-label="STRING"`, `aria-labelledby="IDREF"` | Captions are provided by aria labels. |
+| `aria-sort="VALUE"` | Provides the sorting direction of the column header. |
+
+## Development considerations
+
+### Common do's and don'ts
+
+- **Do** provide a `caption` or `slot="caption"` that describes the table purpose.
+- **Do** keep visible header text for sortable columns.
+- **Don't** use `hide-label` on a sortable column without an alternative accessible name.
+
+## Tests
+
+### Automated
+
+| Technology | Support |
+| --- | --- |
+| AXE-Core (WCAG 2.2 AA, Best-Practice) | ✅ |
+| High-Contrast Mode (light/dark) | ✅ |
+| Text-Zoom (200%) | ✅ |
+
+### Manual
+
+| Technology | Support |
+| --- | --- |
+| Keyboard | ✅ |
+| Screen reader (VoiceOver, NVDA) | 🟠 (Partially supported, [Safari issues 1](https://adrianroselli.com/2022/07/its-mid-2022-and-browsers-mostly-safari-still-break-accessibility-via-display-properties.html), [Safari issues 2](https://adrianroselli.com/2018/02/tables-css-display-properties-and-aria.html)) |
+
+## API
+
+### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `caption` | `string` | `undefined` | Sets a screen-reader-only accessible caption that describes the table's content; it is not visible in the browser. Use an element with `slot="caption"` for a visible caption instead. |
+| `compact` | `boolean` | `false` | Reduces the cell padding and spacing for a more condensed table layout in data-dense UIs. |
+| `layout` | `'auto'` `'fixed'` | `'auto'` | Controls the CSS `table-layout` algorithm: `auto` sizes columns to fit their content, `fixed` distributes width equally. |
+| `sticky` _(experimental)_ | `boolean` | `false` | @experimental Makes the scroll position indicator sticky at the viewport edge while scrolling, indicating overflow in the table. |
+
+### Events
+
+| Event | Type | Description |
+| --- | --- | --- |
+| `update` | `CustomEvent<TableUpdateEventDetail>`<br>`{ id: string; active?: boolean; direction?: Direction }` | Emitted when the user clicks a sortable column header, carrying the new sort configuration in the event detail. |
+
+### Slots
+
+| Slot | Required | Allowed tag names | Description |
+| --- | --- | --- | --- |
+| `caption` | no | — | Shows a caption that describes the content of the table. |
+| _(default)_ | no | — | Default slot for the table content. |
+
+### CSS Variables
+
+| CSS Variable | Default | Description |
+| --- | --- | --- |
+| `--p-table-scroll-indicator-top` | `0px` | Defines the distance from the top of the viewport at which the scroll indicator sticks when scrolling down and `sticky` is enabled. |
+| `--p-table-scroll-indicator-bottom` | `0px` | Defines the distance from the bottom of the viewport at which the scroll indicator sticks when scrolling up and `sticky` is enabled. |
+
+## 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-table-body`
+
+Allowed parent: `p-table`.
+
+#### Slots
+
+| Slot | Required | Allowed tag names | Description |
+| --- | --- | --- | --- |
+| _(default)_ | no | — | Default slot for the table body content. |
+
+### `p-table-cell`
+
+Allowed parent: `p-table-row`.
+
+#### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `multiline` | `boolean` | `false` | Allows slotted text to wrap onto multiple lines instead of being forced onto a single line. |
+
+#### Slots
+
+| Slot | Required | Allowed tag names | Description |
+| --- | --- | --- | --- |
+| _(default)_ | no | — | Default slot for the table cell content. |
+
+### `p-table-head`
+
+Allowed parent: `p-table`.
+
+#### Slots
+
+| Slot | Required | Allowed tag names | Description |
+| --- | --- | --- | --- |
+| _(default)_ | no | — | Default slot for the table head content. |
+
+### `p-table-head-cell`
+
+Allowed parents: `p-table-head-row`, `p-table-row`.
+
+#### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `hideLabel` | `boolean` | `false` | Hides the visible column label while keeping it accessible to screen readers. Only applies when `sort` is not set. |
+| `multiline` | `boolean` | `false` | Allows the column header text to wrap onto multiple lines instead of being truncated to a single line. |
+| `sort` | `TableHeadCellSort` | `undefined` | Configures sorting behavior for this column by providing an `id`, `active` state, and current `direction` (`asc` or `desc`). |
+
+#### Slots
+
+| Slot | Required | Allowed tag names | Description |
+| --- | --- | --- | --- |
+| _(default)_ | no | — | Default slot for the table head cell content. |
+
+### `p-table-head-row`
+
+Allowed parent: `p-table-head`.
+
+#### Slots
+
+| Slot | Required | Allowed tag names | Description |
+| --- | --- | --- | --- |
+| _(default)_ | no | — | Default slot for the table head row content. |
+
+### `p-table-row`
+
+Allowed parents: `p-table-body`, `p-table-head`.
+
+#### Slots
+
+| Slot | Required | Allowed tag names | Description |
+| --- | --- | --- | --- |
+| _(default)_ | no | — | Default slot for the table row content. |
+
+## Examples
+
+| Example | When to use | File |
+| --- | --- | --- |
+| Default | Minimal default configuration. | [./examples/Default.ts](./examples/Default.ts) |
+| Caption via Property | A caption that describes the content of the table is mandatory to fulfill accessibility criteria. | [./examples/CaptionProperty.ts](./examples/CaptionProperty.ts) |
+| Caption via Slot | Instead of using the the property, the table's caption can be provided via the `caption` slot. | [./examples/CaptionSlot.ts](./examples/CaptionSlot.ts) |
+| Layout: fixed | By setting `layout` to `fixed`, you can take full control over each column width, which would otherwise be controlled by its content. | [./examples/LayoutFixed.ts](./examples/LayoutFixed.ts) |
+| Sortable Columns | The `p-table`'s column headers can be configured by setting properties on each `p-table-head-cell`. | [./examples/Sorting.ts](./examples/Sorting.ts) |
+| Hide Column Label | Sometimes you want to hide the visible label of a `p-table-head-cell`, for example when the column's content is self-explanatory. | [./examples/HideLabel.ts](./examples/HideLabel.ts) |
+| Advanced Table | The appearance of a table's contents can be customized as illustrated in the following example. | [./examples/Advanced.ts](./examples/Advanced.ts) |

package/skill/references/components/p-tabs/examples/ActiveTab.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-tabs [activeTabIndex]="1" [aria]="{'aria-label': 'Some label for the tablist', 'aria-description': 'Some description for the tablist'}">
+        <p-tabs-item label="Tab One">
+          <p-text>
+            Tab Content One
+          </p-text>
+        </p-tabs-item>
+        <p-tabs-item label="Tab Two">
+          <p-text>
+            Tab Content Two
+          </p-text>
+        </p-tabs-item>
+        <p-tabs-item label="Tab Three">
+          <p-text>
+            Tab Content Three
+          </p-text>
+        </p-tabs-item>
+      </p-tabs>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

package/skill/references/components/p-tabs/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-tabs [aria]="{'aria-label': 'Some label for the tablist', 'aria-description': 'Some description for the tablist'}">
+        <p-tabs-item label="Tab One">
+          <p-text>
+            Tab Content One
+          </p-text>
+        </p-tabs-item>
+        <p-tabs-item label="Tab Two">
+          <p-text>
+            Tab Content Two
+          </p-text>
+        </p-tabs-item>
+        <p-tabs-item label="Tab Three">
+          <p-text>
+            Tab Content Three
+          </p-text>
+        </p-tabs-item>
+      </p-tabs>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

package/skill/references/components/p-tabs/examples/Gradient.ts

@@ -0,0 +1,114 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <p-tabs [aria]="{'aria-label': 'Some label for the tablist', 'aria-description': 'Some description for the tablist'}">
+        <p-tabs-item label="Tab 1">
+          <p-text>
+            Tab Content 1
+          </p-text>
+        </p-tabs-item>
+        <p-tabs-item label="Tab 2">
+          <p-text>
+            Tab Content 2
+          </p-text>
+        </p-tabs-item>
+        <p-tabs-item label="Tab 3">
+          <p-text>
+            Tab Content 3
+          </p-text>
+        </p-tabs-item>
+        <p-tabs-item label="Tab 4">
+          <p-text>
+            Tab Content 4
+          </p-text>
+        </p-tabs-item>
+        <p-tabs-item label="Tab 5">
+          <p-text>
+            Tab Content 5
+          </p-text>
+        </p-tabs-item>
+        <p-tabs-item label="Tab 6">
+          <p-text>
+            Tab Content 6
+          </p-text>
+        </p-tabs-item>
+        <p-tabs-item label="Tab 7">
+          <p-text>
+            Tab Content 7
+          </p-text>
+        </p-tabs-item>
+        <p-tabs-item label="Tab 8">
+          <p-text>
+            Tab Content 8
+          </p-text>
+        </p-tabs-item>
+        <p-tabs-item label="Tab 9">
+          <p-text>
+            Tab Content 9
+          </p-text>
+        </p-tabs-item>
+        <p-tabs-item label="Tab 10">
+          <p-text>
+            Tab Content 10
+          </p-text>
+        </p-tabs-item>
+        <p-tabs-item label="Tab 11">
+          <p-text>
+            Tab Content 11
+          </p-text>
+        </p-tabs-item>
+        <p-tabs-item label="Tab 12">
+          <p-text>
+            Tab Content 12
+          </p-text>
+        </p-tabs-item>
+        <p-tabs-item label="Tab 13">
+          <p-text>
+            Tab Content 13
+          </p-text>
+        </p-tabs-item>
+        <p-tabs-item label="Tab 14">
+          <p-text>
+            Tab Content 14
+          </p-text>
+        </p-tabs-item>
+        <p-tabs-item label="Tab 15">
+          <p-text>
+            Tab Content 15
+          </p-text>
+        </p-tabs-item>
+        <p-tabs-item label="Tab 16">
+          <p-text>
+            Tab Content 16
+          </p-text>
+        </p-tabs-item>
+        <p-tabs-item label="Tab 17">
+          <p-text>
+            Tab Content 17
+          </p-text>
+        </p-tabs-item>
+        <p-tabs-item label="Tab 18">
+          <p-text>
+            Tab Content 18
+          </p-text>
+        </p-tabs-item>
+        <p-tabs-item label="Tab 19">
+          <p-text>
+            Tab Content 19
+          </p-text>
+        </p-tabs-item>
+        <p-tabs-item label="Tab 20">
+          <p-text>
+            Tab Content 20
+          </p-text>
+        </p-tabs-item>
+      </p-tabs>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

package/skill/references/components/p-tabs/examples/Labelling.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-tabs [aria]="{'aria-label': 'Some label for the tablist', 'aria-description': 'Some description for the tablist'}">
+        <p-tabs-item label="Tab One">
+          <p-text>
+            Tab Content One
+          </p-text>
+        </p-tabs-item>
+        <p-tabs-item label="Tab Two">
+          <p-text>
+            Tab Content Two
+          </p-text>
+        </p-tabs-item>
+        <p-tabs-item label="Tab Three">
+          <p-text>
+            Tab Content Three
+          </p-text>
+        </p-tabs-item>
+      </p-tabs>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}