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

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

@@ -0,0 +1,78 @@
+# p-display
+
+> **Deprecated:** since v4.0.0, will be removed with next major release. Please use `p-heading` instead.
+
+`p-display` is used to highlight and specify heading styling and hierarchy in documents.
+
+> **Recommendation**
+>
+> Although the component is very sophisticated, it's recommended (if possible) to use the corresponding utility classes of the "@porsche-design-system/components-{js | angular | react | vue}/tailwindcss" sub-package or any of the other styling solutions for best performance since way less DOM nodes are required to render. Further information can be found [here](../../styles/tailwindcss.md).
+
+## Usage
+
+p-display is used to highlight and specify heading styling and hierarchy.
+
+### Do's:
+
+- Use p-display for standout moments like hero intros, emotional statements, or key statistics.
+- Choose from display-small, display-medium, or display-large depending on the visual weight required.
+- Center-align p-display styles for marketing, landing, or intro sections to enhance visual impact.
+- Ensure generous spacing around p-display elements to give them room to breathe.
+
+### Don't:
+
+- Don’t use p-display styles for standard section headings or body text—use p-heading or p-text instead.
+- Don’t mix multiple p-display sizes on the same screen unless clearly structured (e.g. in a visual hierarchy).
+
+## Accessibility support
+
+This component does not include any special accessibility features.
+
+## Development considerations
+
+### Heading hierarchy
+
+While using the `Display` component, take care of the correct heading hierarchy which can be adjusted through the `tag` property. Keep in mind that the visual appearance must not always be identical with the semantic hierarchy.
+
+#### Best practices
+
+- Use one unique `h1` per page that describes what that page is about.
+- Use headings to describe the content below. Do not use an HTML heading just to make the text appear bigger or stand out.
+- Use heading levels like the index of a book: hierarchical.
+- Do not choose a heading by its size, but by its level in the context of the content.
+- Heading hierarchy should not increase by more than one level at a time.
+- Do not skip a heading level from the top down.
+
+### Common do's and don'ts
+
+- **Do** use the `tag` prop to reflect semantic hierarchy, not just visual `size`.
+- **Do** keep one unique `h1` per page for the primary page topic.
+- **Don't** use `tag="h1"` on display text that is not the main page title.
+
+## API
+
+### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `align` | `'start'` `'center'` `'end'` `'inherit'` | `'start'` | Sets the horizontal text alignment (`start`, `center`, `end`, or `inherit`). |
+| `color` | `'primary'` `'inherit'` | `'primary'` | Sets the text color using PDS color tokens. |
+| `ellipsis` | `boolean` | `false` | Truncates the text with an ellipsis when it overflows the container on a single line. |
+| `size` | `'small'` `'medium'` `'large'` `'inherit'`<br>`BreakpointCustomizable<DisplaySize>` | `'large'` | Sets the visual text size. Supports responsive breakpoint values. |
+| `tag` | `undefined` `'h1'` `'h2'` `'h3'` `'h4'` `'h5'` `'h6'` | `undefined` | Sets the HTML heading tag (h1–h6) for correct document outline placement. When omitted, the tag is inferred from `size`. |
+
+### Slots
+
+| Slot | Required | Allowed tag names | Description |
+| --- | --- | --- | --- |
+| _(default)_ | no | — | Default slot for the display text. |
+
+## Examples
+
+| Example | When to use | File |
+| --- | --- | --- |
+| Default | Minimal default configuration. | [./examples/Default.ts](./examples/Default.ts) |
+| Size | There are predefined fluid text sizes for the component which should cover most use cases. | [./examples/Size.ts](./examples/Size.ts) |
+| Responsive | Responsive | [./examples/SizeResponsive.ts](./examples/SizeResponsive.ts) |
+| Semantics | To provide more contextual HTML semantics you can either pass them with the `tag` property or directly inside a slot. | [./examples/Semantics.ts](./examples/Semantics.ts) |
+| Color | Predefined theme-based colors are available, but `inherit` can also be used to define a custom color. | [./examples/Color.ts](./examples/Color.ts) |

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

package/skill/references/components/p-divider/examples/Responsive.ts

@@ -0,0 +1,15 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <div class="lg:flex lg:h-[150px]">
+        <p-divider [direction]="{'base': 'horizontal', 'l': 'vertical'}"></p-divider>
+      </div>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

package/skill/references/components/p-divider/examples/Vertical.ts

@@ -0,0 +1,15 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <div class="flex h-[100px]">
+        <p-divider direction="vertical"></p-divider>
+      </div>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

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

@@ -0,0 +1,49 @@
+# p-divider
+
+The `p-divider` is used as 'horizontal or vertical rule' and displays a dividing line. The component is self-closing. Slotted content between the component tags won't be displayed.
+
+## Usage
+
+### Do:
+
+- Use to create a visual separation between related sections of content.
+- Use to separate content into clear groups.
+- Use when other options for structuring content are not sufficient.
+
+### Don't:
+
+- Don't use dividers to structure content, rather work with more space for clustering
+- Don't use it for decorative purposes unless it's necessary.
+- Avoid full-bleed dividers to separate page sections.
+
+## Accessibility support
+
+This component does not include any special accessibility features.
+
+## Development considerations
+
+### Structure
+
+A divider is visual separation only. Use headings, landmarks, or section structure to communicate content groups.
+
+### Common do's and don'ts
+
+- **Do** pair dividers with headings or landmarks that describe the sections they separate.
+- **Don't** rely on a divider alone to communicate a new major section.
+
+## API
+
+### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `color` | `'contrast-lower'` `'contrast-low'` `'contrast-medium'` `'contrast-high'` | `'contrast-lower'` | Sets the color of the divider line using PDS contrast tokens. |
+| `direction` | `'vertical'` `'horizontal'`<br>`BreakpointCustomizable<DividerDirection>` | `'horizontal'` | Sets the orientation of the divider to `horizontal` or `vertical`. Supports responsive breakpoint values. |
+
+## Examples
+
+| Example | When to use | File |
+| --- | --- | --- |
+| Default | Minimal default configuration. | [./examples/Default.ts](./examples/Default.ts) |
+| Vertical | **Hint:** The component has not an implicit vertical height unless we set a container which provides it or define the height on the component itself. | [./examples/Vertical.ts](./examples/Vertical.ts) |
+| Responsive | You can change the divider's direction by using different major breakpoints `xs`, `s`, `m`, `l`, `xl`. | [./examples/Responsive.ts](./examples/Responsive.ts) |

package/skill/references/components/p-drilldown/examples/CustomContent.ts

@@ -0,0 +1,166 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule, type DrilldownUpdateEventDetail } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <nav aria-label="Main">
+        <p-button type="button" [aria]="{'aria-haspopup': 'dialog'}" (click)="onClick()">
+          Open Drilldown
+        </p-button>
+        <p-drilldown [open]="open" [activeIdentifier]="activeIdentifier" class="[--p-drilldown-grid-template:repeat(5,auto)_minmax(0,1fr)/auto]" (update)="onUpdate($event)" (dismiss)="onDismiss()">
+          <p-drilldown-item identifier="id-1" label="Motorsport" class="[--p-drilldown-grid-template:auto/repeat(2,minmax(0,1fr))] [--p-drilldown-gap:0px_16px]">
+            <p-drilldown-item identifier="id-1-1" label="718">
+              <p-model-signature slot="header" model="718"></p-model-signature>
+              <p-button-tile slot="button" label="Some label" description="718" weight="semi-bold" [compact]="true" [aspectRatio]="{'base': '1/1', 's': '9/16'}" class="mb-fluid-sm">
+                <img srcset="assets/porsche-963@2x.webp 2x" src="assets/porsche-963.webp" [width]="636" [height]="847" alt="Porsche 963" />
+              </p-button-tile>
+              <p-drilldown-link href="#">
+                Some anchor
+              </p-drilldown-link>
+              <p-drilldown-link href="#">
+                Some anchor
+              </p-drilldown-link>
+              <p-drilldown-link href="#">
+                Some anchor
+              </p-drilldown-link>
+              <p-drilldown-link href="#">
+                Some anchor
+              </p-drilldown-link>
+            </p-drilldown-item>
+            <p-drilldown-item identifier="id-1-2" label="911">
+              <p-model-signature slot="header" model="911"></p-model-signature>
+              <p-button-tile slot="button" label="Some label" description="911" weight="semi-bold" [compact]="true" [aspectRatio]="{'base': '1/1', 's': '9/16'}" class="mb-fluid-sm">
+                <img srcset="assets/porsche-963@2x.webp 2x" src="assets/porsche-963.webp" [width]="636" [height]="847" alt="Porsche 963" />
+              </p-button-tile>
+              <p-drilldown-link href="#">
+                Some anchor
+              </p-drilldown-link>
+              <p-drilldown-link href="#">
+                Some anchor
+              </p-drilldown-link>
+            </p-drilldown-item>
+            <p-drilldown-link href="#">
+              Some anchor
+            </p-drilldown-link>
+            <p-drilldown-link href="#" aria-current="page">
+              Some anchor
+            </p-drilldown-link>
+            <p-drilldown-link href="#">
+              Some anchor
+            </p-drilldown-link>
+            <p-drilldown-link href="#">
+              Some anchor
+            </p-drilldown-link>
+            <p-drilldown-link href="#">
+              Some anchor
+            </p-drilldown-link>
+            <p-drilldown-link href="#">
+              Some anchor
+            </p-drilldown-link>
+            <p-drilldown-link href="#">
+              Some anchor
+            </p-drilldown-link>
+            <p-drilldown-link href="#">
+              Some anchor
+            </p-drilldown-link>
+            <p-drilldown-link href="#">
+              Some anchor
+            </p-drilldown-link>
+          </p-drilldown-item>
+          <p-drilldown-item identifier="id-2" label="Some label">
+            <p-drilldown-item identifier="id-2-1" label="Some label">
+              <p-drilldown-link href="#">
+                Some anchor
+              </p-drilldown-link>
+              <p-drilldown-link href="#">
+                Some anchor
+              </p-drilldown-link>
+              <p-drilldown-link href="#">
+                Some anchor
+              </p-drilldown-link>
+              <p-drilldown-link href="#">
+                Some anchor
+              </p-drilldown-link>
+            </p-drilldown-item>
+            <p-drilldown-item identifier="id-2-2" label="Some label">
+              <p-drilldown-link href="#">
+                Some anchor
+              </p-drilldown-link>
+              <p-drilldown-link href="#">
+                Some anchor
+              </p-drilldown-link>
+              <p-drilldown-link href="#">
+                Some anchor
+              </p-drilldown-link>
+            </p-drilldown-item>
+            <p-drilldown-link href="#">
+              Some anchor
+            </p-drilldown-link>
+            <p-drilldown-link href="#">
+              Some anchor
+            </p-drilldown-link>
+            <p-drilldown-link href="#">
+              Some anchor
+            </p-drilldown-link>
+            <p-drilldown-link href="#">
+              Some anchor
+            </p-drilldown-link>
+          </p-drilldown-item>
+          <p-drilldown-item identifier="id-3" label="Some label">
+            <p-drilldown-link href="#">
+              Some anchor
+            </p-drilldown-link>
+            <p-drilldown-link href="#">
+              Some anchor
+            </p-drilldown-link>
+            <p-drilldown-link href="#">
+              Some anchor
+            </p-drilldown-link>
+            <p-drilldown-link href="#">
+              Some anchor
+            </p-drilldown-link>
+          </p-drilldown-item>
+          <p-drilldown-item identifier="id-4" label="Some label">
+            <p-drilldown-link href="#">
+              Some anchor
+            </p-drilldown-link>
+            <p-drilldown-link href="#">
+              Some anchor
+            </p-drilldown-link>
+            <p-drilldown-link href="#">
+              Some anchor
+            </p-drilldown-link>
+          </p-drilldown-item>
+          <p-drilldown-item identifier="id-5" label="Some label">
+            <p-drilldown-link href="#">
+              Some anchor
+            </p-drilldown-link>
+            <p-drilldown-link href="#">
+              Some anchor
+            </p-drilldown-link>
+          </p-drilldown-item>
+          <p-link href="#" variant="secondary" icon="external" class="self-end">
+            Some external anchor
+          </p-link>
+        </p-drilldown>
+      </nav>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {
+  activeIdentifier = "id-1";
+  open = false;
+
+  onClick() {
+    this.open = true;
+  }
+  onUpdate(e: CustomEvent<DrilldownUpdateEventDetail>) {
+    this.activeIdentifier = e.detail.activeIdentifier;
+  }
+  onDismiss() {
+    this.open = false;
+  }
+}

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

@@ -0,0 +1,119 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule, type DrilldownUpdateEventDetail } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <nav aria-label="Main">
+        <p-button type="button" [aria]="{'aria-haspopup': 'dialog'}" (click)="onClick()">
+          Open Drilldown
+        </p-button>
+        <p-drilldown [open]="open" [activeIdentifier]="activeIdentifier" (update)="onUpdate($event)" (dismiss)="onDismiss()">
+          <p-drilldown-item identifier="id-1" label="Some Label (1)">
+            <p-drilldown-item identifier="id-1-1" label="Some Label (1-1)">
+              <p-drilldown-link href="#">
+                Some anchor (1-1)
+              </p-drilldown-link>
+              <p-drilldown-link>
+                <a href="#">
+                  Some anchor (1-1)
+                </a>
+              </p-drilldown-link>
+            </p-drilldown-item>
+            <p-drilldown-item identifier="id-1-2" label="Some Label (1-2)">
+              <p-drilldown-link href="#">
+                Some anchor (1-2)
+              </p-drilldown-link>
+              <p-drilldown-link href="#">
+                Some anchor (1-2)
+              </p-drilldown-link>
+              <p-drilldown-link href="#">
+                Some anchor (1-2)
+              </p-drilldown-link>
+              <p-drilldown-item identifier="id-1-2-1" label="Some Label (1-2-1)">
+                <p-drilldown-link href="#">
+                  Some anchor (1-2-1)
+                </p-drilldown-link>
+                <p-drilldown-link href="#">
+                  Some anchor (1-2-1)
+                </p-drilldown-link>
+              </p-drilldown-item>
+              <p-drilldown-link href="#">
+                Some anchor (1-2)
+              </p-drilldown-link>
+            </p-drilldown-item>
+            <p-drilldown-link href="#">
+              Some anchor (1-1)
+            </p-drilldown-link>
+            <p-drilldown-link href="#">
+              Some anchor (1-1)
+            </p-drilldown-link>
+            <p-drilldown-link href="#">
+              Some anchor (1-1)
+            </p-drilldown-link>
+          </p-drilldown-item>
+          <p-drilldown-item identifier="id-2" label="Some Label (2)">
+            <p-drilldown-link href="#">
+              Some anchor (2)
+            </p-drilldown-link>
+            <p-drilldown-link href="#">
+              Some anchor (2)
+            </p-drilldown-link>
+            <p-drilldown-link href="#">
+              Some anchor (2)
+            </p-drilldown-link>
+            <p-drilldown-link href="#">
+              Some anchor (2)
+            </p-drilldown-link>
+          </p-drilldown-item>
+          <p-drilldown-item identifier="id-3" label="Some Label (3)">
+            <p-drilldown-link href="#">
+              Some anchor (3)
+            </p-drilldown-link>
+            <p-drilldown-link href="#">
+              Some anchor (3)
+            </p-drilldown-link>
+            <p-drilldown-link href="#">
+              Some anchor (3)
+            </p-drilldown-link>
+          </p-drilldown-item>
+          <p-drilldown-item identifier="id-4" label="Some Label (4)">
+            <p-drilldown-link href="#">
+              Some anchor (4)
+            </p-drilldown-link>
+            <p-drilldown-link href="#">
+              Some anchor (4)
+            </p-drilldown-link>
+            <p-drilldown-link href="#">
+              Some anchor (4)
+            </p-drilldown-link>
+          </p-drilldown-item>
+          <p-drilldown-item identifier="id-5" label="Some Label (5)">
+            <p-drilldown-link href="#">
+              Some anchor (5)
+            </p-drilldown-link>
+            <p-drilldown-link href="#">
+              Some anchor (5)
+            </p-drilldown-link>
+          </p-drilldown-item>
+        </p-drilldown>
+      </nav>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {
+  activeIdentifier = undefined;
+  open = false;
+
+  onClick() {
+    this.open = true;
+  }
+  onUpdate(e: CustomEvent<DrilldownUpdateEventDetail>) {
+    this.activeIdentifier = e.detail.activeIdentifier;
+  }
+  onDismiss() {
+    this.open = false;
+  }
+}

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

@@ -0,0 +1,168 @@
+# p-drilldown
+
+> **Experimental:** This component is experimental — its API may change in any release. Avoid relying on it in production.
+
+> **Experimental Component**
+>
+> The `p-drilldown` component is experimental and might be changed or removed in a future release.
+
+The `p-drilldown` component is meant for displaying an infinite multilevel structure in a drilldown menu that overlays the page content from the start side of the screen. It is a controlled component that gives you flexible control over its behavior.
+
+The basic concept of the component is to have a button that opens the `p-drilldown` with an infinite multilevel structure. The levels are generated out of `p-drilldown-item` which generates a list of cascade buttons to navigate to a deeper level, back buttons and a header section on mobile view. These items can be filled with e.g. `p-drilldown-link`, another `p-drilldown-item` or any HTML element.
+
+The visibility of `p-drilldown` can be controlled by its `open` property.
+
+It's **obligatory** that each `p-drilldown-item` has a unique `identifier` and `label` defined.
+
+Since it's a controlled component it's necessary to register an event listener for the `dismiss` and `update` event in order to get notified when `p-drilldown` needs to be closed or navigated to another hierarchy level.
+
+## Usage
+
+### Do:
+
+- Use Drilldown for multilevel purposes.
+- Use Drilldown for multilevel on desktop & mobile.
+- Use a button-pure with a burger icon as the main trigger for the Drilldown component.
+- Use additional interaction items to trigger component.
+- Use a multilevel hierarchy that matches the two-layer capability of the component.
+- Use the first layer for multilevel targets or categories for link lists.
+- Use the second layer only if necessary.
+- Use section headings on the second layer for a group of links.
+- Use link-tile on the second layer for important links.
+
+### Don't:
+
+- Don't put too much additional information into the component.
+- Don't use other interaction components than mentioned.
+- Don't manipulate the heading in the second layer.
+- Don't implement external links without indicators.
+
+---
+
+## Related components
+
+- [Flyout](../p-flyout/p-flyout.md)
+
+## Accessibility support
+
+The `Drilldown` component uses the native `dialog` element to provide a modal dialog which comes with browser-specific behavior. As a result, accessibility features may vary across different browsers.
+
+### Keyboard
+
+| Key / state | Function |
+| --- | --- |
+| `Tab`, `Shift-Tab` | Moves focus to the next (or previous) focusable element inside the dialog. Focus is trapped (browser behavior). |
+| `ESC` | Closes the dialog. |
+| `focus` on trigger element | The focus is returned to the trigger element after closing the dialog (browser behavior). |
+
+### ARIA enhancements
+
+#### External **ARIA** provided by the `aria` property:
+
+| ARIA | Usage |
+| --- | --- |
+| `aria-label` | Defines a string value that labels the dialog element. |
+
+## Development considerations
+
+To inform users that the trigger button opens a `dialog`, the `aria-haspopup` attribute must be set using the `aria` property, e.g.: `aria="{ 'aria-haspopup': 'dialog' }"`.
+
+### Common do's and don'ts
+
+- **Do** use a semantic trigger (usually a button) with a meaningful accessible name.
+- **Do** set `aria-haspopup` through the trigger component `aria` prop.
+- **Do** provide a meaningful dialog label through the drilldown `aria` prop when needed.
+- **Don't** add native `aria-*` attributes directly on the component host.
+
+## API
+
+### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `activeIdentifier` | `string | undefined` | `undefined` | Sets which `p-drilldown-item` (by `identifier`) is currently expanded to show its sub-navigation level. |
+| `aria` | `DrilldownAriaAttribute` | `undefined` | Sets ARIA attributes on the drilldown dialog element for improved screen reader accessibility. |
+| `open` | `boolean` | `false` | Controls whether the drilldown navigation panel is visible. |
+
+### Events
+
+| Event | Type | Description |
+| --- | --- | --- |
+| `dismiss` | `CustomEvent<void>` | Emitted when the user closes the drilldown via the close button or Escape key. |
+| `update` | `CustomEvent<DrilldownUpdateEventDetail>`<br>`{ activeIdentifier: string | undefined }` | Emitted when the active navigation level changes, with the new `activeIdentifier` in the event detail. |
+
+### Controlled properties
+
+- `open` — a controlled prop: the component does **not** update it itself. Handle the `dismiss` event and assign the new value to `open` yourself, or the change will not take effect.
+- `activeIdentifier` — a controlled prop: the component does **not** update it itself. Handle the `update` event and assign the new value to `activeIdentifier` yourself, or the change will not take effect.
+
+### Slots
+
+| Slot | Required | Allowed tag names | Description |
+| --- | --- | --- | --- |
+| _(default)_ | no | — | Default slot to render p-drilldown items. |
+
+### CSS Variables
+
+| CSS Variable | Default | Description |
+| --- | --- | --- |
+| `--p-drilldown-grid-template` | `auto/auto` | Overrides the CSS `grid-template` of the default slot container, allowing custom grid layout for drilldown items. |
+| `--p-drilldown-gap` | `8px` | Overrides the gap between drilldown items in the default slot container. |
+
+## 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-drilldown-item` _(experimental)_
+
+> **Experimental:** This component is experimental — its API may change in any release. Avoid relying on it in production.
+
+Allowed parents: `p-drilldown`, `p-drilldown-item`.
+
+#### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `cascade` | `boolean` | `false` | Private property set by the component itself. |
+| `identifier` _(required)_ | `string` | `undefined` | Sets the unique identifier matched against the drilldown's `activeIdentifier` to determine if this item is shown. |
+| `label` | `string` | `undefined` | Sets the text used for the back button, sticky header, and cascade button that navigates into this navigation level. |
+| `primary` | `boolean` | `false` | Private property set by the component itself. |
+| `secondary` | `boolean` | `false` | Private property set by the component itself. |
+
+#### Slots
+
+| Slot | Required | Allowed tag names | Description |
+| --- | --- | --- | --- |
+| _(default)_ | no | — | Default slot for the main content. |
+| `button` | no | — | Shows a custom button to reach a deeper level of the navigation structure. |
+| `header` | no | — | Shows a custom header section on mobile view. |
+
+### `p-drilldown-link` _(experimental)_
+
+> **Experimental:** This component is experimental — its API may change in any release. Avoid relying on it in production.
+
+Allowed parents: `p-drilldown`, `p-drilldown-item`.
+
+#### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `active` | `boolean` | `false` | Visually marks the link as the currently active navigation item, e.g. the current page. |
+| `aria` | `DrilldownLinkAriaAttribute` | `undefined` | Sets ARIA attributes on the link for improved accessibility. Only applies when `href` is set. |
+| `download` | `string` | `undefined` | Sets the native `download` attribute to trigger a file download. Only applies when `href` is set. |
+| `href` | `string` | `undefined` | When set, the component renders as an anchor navigating to this URL. Otherwise, provide a slotted anchor element. |
+| `rel` | `string` | `undefined` | Sets the `rel` attribute on the link element (e.g. `noopener`). Only applies when `href` is set. |
+| `target` | `'_self'` `'_blank'` `'_parent'` `'_top'` `'string'` | `'_self'` | Specifies where to open the linked URL (e.g. `_self`, `_blank`). Only applies when `href` is set. |
+
+#### Slots
+
+| Slot | Required | Allowed tag names | Description |
+| --- | --- | --- | --- |
+| _(default)_ | no | — | Default slot to render the link label. |
+
+## Examples
+
+| Example | When to use | File |
+| --- | --- | --- |
+| Default | Minimal default configuration. | [./examples/Default.ts](./examples/Default.ts) |
+| Example with custom content | To give more flexibility, it's possible to use custom slots `slot="button"` (renders a custom cascade button) and/or `slot="header"` (renders a custom header on mobile view). | [./examples/CustomContent.ts](./examples/CustomContent.ts) |

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

@@ -0,0 +1,15 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <p-fieldset label="Some legend label">
+        <p-input-text label="Some label" name="some-name"></p-input-text>
+      </p-fieldset>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

package/skill/references/components/p-fieldset/examples/Required.ts

@@ -0,0 +1,16 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <p-fieldset label="Some legend label" [required]="true">
+        <p-input-text label="Some label" name="some-name-1" [required]="true"></p-input-text>
+        <p-input-text label="Some label" name="some-name-2" [required]="true" class="mt-fluid-sm"></p-input-text>
+      </p-fieldset>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}