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

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

@@ -0,0 +1,18 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <p-fieldset>
+        <span slot="label">
+          Some legend label
+        </span>
+        <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/SlottedMessage.ts

@@ -0,0 +1,18 @@
+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" state="error">
+        <p-input-text label="Some label" name="some-name"></p-input-text>
+        <span slot="message">
+          Some error message
+        </span>
+      </p-fieldset>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

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

@@ -0,0 +1,88 @@
+# p-fieldset
+
+The `p-fieldset` is a grouping component for wrapping contextual associated form elements. Its visible part is an HTML *legend* element, which can be seen like a headline for describing the meaning of a form block. You can see some usage examples on our [form patterns section](https://designsystem.porsche.com/patterns/forms/resources/).
+
+## Usage
+
+### Do:
+
+- Use to group related fields together to make them more organized and easier to understand for users.
+- Use descriptive and clear labels for the field sets to help users quickly understand what information is being requested.
+- Use for grouping several form controls as well as labels within a form.
+- Use it for grouping several checkboxes.
+- Use it for creating a date picker.
+- Use consistent formatting and styling for field sets to maintain visual consistency and improve the overall user experience.
+- Use field sets to control the visibility of groups of fields that are not always necessary, such as advanced options or additional information.
+- Test your field sets with users to ensure they are effective in improving the usability of your forms or page layouts.
+
+### Don't:
+
+- Don't use too many field sets on a single form or page layout.
+- Don't use to hide important information or fields that users need to complete a form.
+- Don't rely solely on field sets to improve the usability of your forms or page layouts.
+
+---
+
+## Behavior
+
+### Sections including form elements
+
+[Form pattern guideline](https://designsystem.porsche.com/patterns/forms).
+
+## Accessibility support
+
+### ARIA enhancements
+
+#### External **ARIA** provided by the `aria` property:
+
+| ARIA | Usage |
+| --- | --- |
+| `role="radiogroup"` | Changes the default role of `group` to `radiogroup` |
+
+#### Internal **ARIA** that is managed by the component:
+
+| ARIA | Usage |
+| --- | --- |
+| `role="alert"` | When content is populated or changed in `state="error"`, the component announces it immediately. |
+| `aria-required="true"` | Indicates if all children of the fieldset group are required. |
+| `aria-invalid="true"` | If `error` state is set. |
+| `aria-describedby="IDREF"` | References the accessible description when `state` message is provided. |
+
+## Development considerations
+
+### Common do's and don'ts
+
+- **Do** provide a clear `label` that describes the grouped fields.
+- **Do** use the component state/message API so group validation is announced.
+- **Do** use `aria="{ 'role': 'radiogroup' }"` only when the fieldset contains custom radio controls.
+- **Don't** set `state="error"` without a descriptive `message`.
+
+## API
+
+### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `aria` | `'radiogroup'` | `undefined` | Overrides the ARIA role on the fieldset — use `radiogroup` when grouping radio buttons. |
+| `label` | `string` | `''` | Sets the visible legend text displayed above the grouped form controls. |
+| `labelSize` | `'small'` `'medium'` | `'medium'` | Sets the font size of the fieldset label (`small`, `medium`, or `large`). |
+| `message` | `string` | `''` | Sets the validation feedback message displayed below the fieldset when `state` is `success` or `error`. |
+| `required` | `boolean` | `false` | Marks all controls within the fieldset as required and adds a required indicator to the label. |
+| `state` | `'none'` `'error'` `'success'` | `'none'` | Sets the validation state of the fieldset, controlling the color and style of the feedback message. |
+
+### Slots
+
+| Slot | Required | Allowed tag names | Description |
+| --- | --- | --- | --- |
+| `label` | no | — | Shows a label. Only [phrasing content](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Content_categories#Phrasing_content) is allowed. |
+| _(default)_ | no | — | Default slot for the main content. |
+| `message` | no | — | Shows a state message. Only [phrasing content](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Content_categories#Phrasing_content) is allowed. |
+
+## Examples
+
+| Example | When to use | File |
+| --- | --- | --- |
+| Default | Minimal default configuration. | [./examples/Default.ts](./examples/Default.ts) |
+| Slotted label | Slotted label | [./examples/SlottedLabel.ts](./examples/SlottedLabel.ts) |
+| Slotted message | Slotted message | [./examples/SlottedMessage.ts](./examples/SlottedMessage.ts) |
+| Required | Setting `required="true"` on `p-fieldset` only renders the asterisk on the legend and sets `aria-required` on the underlying `<fieldset>` element. | [./examples/Required.ts](./examples/Required.ts) |

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

package/skill/references/components/p-flag/examples/ResponsiveSize.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-flag name="de" [size]="{'base': 'sm', 'l': '2xl'}" [aria]="{'aria-label': 'Flag of Germany'}"></p-flag>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

package/skill/references/components/p-flag/examples/Size.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-text class="text-[48px]" size="inherit">
+        <p-flag class="me-static-sm" size="inherit" name="de" [aria]="{'aria-label': 'Flag of Germany'}"></p-flag>
+        Some text
+      </p-text>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

package/skill/references/components/p-flag/examples/SizeCssVar.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-flag class="[--p-flag-size:48px]" name="de" [aria]="{'aria-label': 'Flag of Germany'}"></p-flag>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

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

@@ -0,0 +1,68 @@
+# p-flag
+
+The `p-flag` component displays a country or region flag and should be used to communicate geographic context visually.
+
+Flags are universally recognized symbols that enable rapid visual communication. Alongside icons, colors, and typography, they are a fundamental part of the Porsche design language and help create a seamless user experience.
+
+## Usage
+
+The following guidelines provide instructions for designers and developers on the appropriate use of the `flag` component for effective communication and user experience.
+
+### Do:
+
+- **Use the `flag` component for country identification.** The primary purpose is to represent a nation, such as specifying a user's country of origin, shipping location, or detailing product availability.
+
+- **Pair the flag with a label for clarity.** While flags are great for quick visual recognition, they can be ambiguous. Always accompany a flag with a country name or an appropriate label to avoid confusion.
+
+- **Use the two-letter ISO 3166-1 alpha-2 code.** This standard ensures consistency, reduces errors, and makes it easier to integrate with other systems and APIs.
+
+### Don't:
+
+- **Don't use flags to represent a language.** Many languages are spoken in multiple countries (e.g., Spanish). A flag represents a nation, not a language. Use language codes or names instead.
+
+- **Don't use flags to represent an emotion or concept.** Flags are powerful symbols of national identity. Using them as generic icons can dilute their meaning and cause user confusion.
+
+- **Don't rely solely on the flag icon.** Always provide an aria-label for accessibility. Screen readers cannot interpret flags, and without a descriptive label, you create an inaccessible user experience.
+
+## Accessibility support
+
+### ARIA enhancements
+
+#### External **ARIA** provided by the `aria` property:
+
+| ARIA | Usage |
+| --- | --- |
+| `aria-label` | Defines a string value that labels the element (through the `alt` attribute). |
+
+## Development considerations
+
+### Common do's and don'ts
+
+- **Do** pass a country or region name through the `aria` prop when the flag conveys meaning.
+- **Do** hide decorative flags from assistive technologies when adjacent text already names the country or region.
+- **Don't** leave informative flags without an accessible name.
+
+## API
+
+### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `aria` | `FlagAriaAttribute` | `undefined` | A map of ARIA attributes to enhance the flag's accessibility. For example, use `{ 'aria-label': 'German flag' }` to provide a descriptive label for screen readers. |
+| `name` | `'ad'` `'ae'` `'al'` `'am'` `'ar'` `'at'` `'au'` `'az'` `'ba'` `'bd'` `'be'` `'bg'` `'bh'` `'bn'` `'bo'` `'br'` `'by'` `'ca'` `'ch'` `'cl'` `'cn'` `'co'` `'cr'` `'cw'` `'cy'` `'cz'` `'de'` `'dk'` `'do'` `'dz'` `'ec'` `'ee'` `'eg'` `'es'` `'fi'` `'fr'` `'gb'` `'ge'` `'gh'` `'gi'` `'gr'` `'gt'` `'hk'` `'hn'` `'hr'` `'ht'` `'hu'` `'id'` `'ie'` `'il'` `'in'` `'is'` `'it'` `'jm'` `'jo'` `'jp'` `'ke'` `'kh'` `'kr'` `'kw'` `'kz'` `'lb'` `'li'` `'lk'` `'lt'` `'lu'` `'lv'` `'ma'` `'mc'` `'md'` `'me'` `'mk'` `'mn'` `'mo'` `'mq'` `'mt'` `'mu'` `'mx'` `'my'` `'ng'` `'nl'` `'no'` `'nz'` `'om'` `'pa'` `'pe'` `'pf'` `'ph'` `'pk'` `'pl'` `'pr'` `'pt'` `'py'` `'qa'` `'re'` `'ro'` `'rs'` `'ru'` `'sa'` `'se'` `'sg'` `'si'` `'sk'` `'sv'` `'th'` `'tn'` `'tr'` `'tt'` `'tw'` `'ua'` `'us'` `'uy'` `'uz'` `'ve'` `'vn'` `'xx'` `'za'` | `'de'` | Specifies the country flag to display. Use the two-letter ISO 3166-1 alpha-2 country code. For example, use `us` for the United States, `de` for Germany, `gb` for Great Britain. |
+| `size` | `'2xs'` `'xs'` `'sm'` `'md'` `'lg'` `'xl'` `'2xl'` `'3xl'` `'4xl'` `'5xl'` `'inherit'`<br>_deprecated:_ `'xx-small'` `'x-small'` `'small'` `'medium'` `'large'` `'x-large'` `'xx-large'`<br>`BreakpointCustomizable<FlagSize>` | `'sm'` | Defines the size of the flag, aligned with the typographic scale used by components such as p-icon, p-spinner, p-text, and p-heading. When set to `inherit`, the size is derived from a custom font-size defined on a parent element, calculated against the global line-height (based on `ex`-unit) to remain visually consistent with other typographic-scale-based components. |
+
+### CSS Variables
+
+| CSS Variable | Default | Description |
+| --- | --- | --- |
+| `--p-flag-size` | — | Defines the width and height of the flag. Overrides the `size` property when set. |
+
+## Examples
+
+| Example | When to use | File |
+| --- | --- | --- |
+| Default | Minimal default configuration. | [./examples/Default.ts](./examples/Default.ts) |
+| Size via Prop | The `size` property offers a set of predefined sizes that cover most use cases. | [./examples/Size.ts](./examples/Size.ts) |
+| Size via CSS Variable | For full control over the flag's dimensions, use the custom CSS variable `--p-flag-size`, which accepts any valid CSS length value. | [./examples/SizeCssVar.ts](./examples/SizeCssVar.ts) |
+| Responsive Size | The `size` property supports `BreakpointCustomizable` values, allowing you to define different sizes for each major breakpoint (`xs`, `s`, `m`, `l`, `xl`). | [./examples/ResponsiveSize.ts](./examples/ResponsiveSize.ts) |

package/skill/references/components/p-flyout/examples/CustomStyling.ts

@@ -0,0 +1,47 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <p-button type="button" [aria]="{'aria-haspopup': 'dialog'}" (click)="onClick()">
+        Open Flyout
+      </p-button>
+
+      <p-flyout [open]="open" [aria]="{'aria-label': 'Some Heading'}" footerBehavior="fixed" class="[--p-flyout-width:90vw]" (dismiss)="onDismiss()">
+        <div class="-mt-(--ref-p-flyout-pt) -mx-(--ref-p-flyout-px) h-[300px]">
+          <img class="w-full h-full object-cover" src="assets/lights.jpg" alt="Some image description" />
+        </div>
+        <p-display class="mt-fluid-md" size="small" tag="h2">
+          Some heading
+        </p-display>
+        <p-text class="mt-fluid-sm">
+          Some paragraph.
+        </p-text>
+        <div slot="footer" class="grid grid-cols-[auto_1fr_auto] gap-static-sm justify-items-center">
+          <p-button-pure icon="arrow-left" type="button" [hideLabel]="true">
+            Prev
+          </p-button-pure>
+          <p-text>
+            1/4
+          </p-text>
+          <p-button-pure icon="arrow-right" type="button" [hideLabel]="true">
+            Next
+          </p-button-pure>
+        </div>
+      </p-flyout>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {
+  open = false;
+
+  onClick() {
+    this.open = true;
+  }
+  onDismiss() {
+    this.open = false;
+  }
+}

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

@@ -0,0 +1,44 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <p-button type="button" [aria]="{'aria-haspopup': 'dialog'}" (click)="onClick()">
+        Open Flyout
+      </p-button>
+
+      <p-flyout [open]="open" [aria]="{'aria-label': 'Some Heading'}" (dismiss)="onDismiss()">
+        <p-heading slot="header" size="large" tag="h2">
+          Some Heading
+        </p-heading>
+        <p-text>
+          Some Content
+        </p-text>
+        <div slot="footer">
+          <p-button type="button">
+            Proceed
+          </p-button>
+          <p-button type="button" variant="secondary">
+            Cancel
+          </p-button>
+        </div>
+        <p-text slot="sub-footer">
+          Some additional Sub-Footer
+        </p-text>
+      </p-flyout>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {
+  open = false;
+
+  onClick() {
+    this.open = true;
+  }
+  onDismiss() {
+    this.open = false;
+  }
+}

package/skill/references/components/p-flyout/examples/Form.ts

@@ -0,0 +1,47 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+    <p-button type="button" [aria]="{ 'aria-haspopup': 'dialog' }" (click)="onOpen()">Open Flyout</p-button>
+    <p-flyout [open]="isFlyoutOpen" (dismiss)="onDismiss()" [aria]="{ 'aria-label': 'Some Heading' }">
+      <p-heading slot="header" size="large" tag="h2">Some Heading</p-heading>
+      <form id="some-form" (submit)="onSubmit($event)">
+        <p-checkbox name="some-checkbox" label="Some Label"></p-checkbox>
+        <p-textarea name="some-textarea" label="Some Label"></p-textarea>
+      </form>
+      <p-button slot="footer" type="submit" form="some-form">Submit</p-button>
+      <p-button slot="footer" type="reset" [variant]="'secondary'" form="some-form">Reset</p-button>
+      <p-text slot="sub-footer">
+        Last submitted data:
+        <br/><br/>
+        checkbox: {{checkboxValue}}
+        <br/>
+        textarea: {{textareaValue}}
+      </p-text>
+    </p-flyout>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule],
+})
+export class ExampleComponent {
+  isFlyoutOpen = false;
+  checkboxValue: string = 'none';
+  textareaValue: string = 'none';
+
+  onOpen() {
+    this.isFlyoutOpen = true;
+  }
+  onDismiss() {
+    this.isFlyoutOpen = false;
+  }
+
+  onSubmit(e: Event): void {
+    e.preventDefault();
+    const formData = new FormData(e.target as HTMLFormElement);
+    this.checkboxValue = formData.get('some-checkbox')?.toString() || 'none';
+    this.textareaValue = formData.get('some-textarea')?.toString() || 'none';
+  }
+}

package/skill/references/components/p-flyout/examples/StickyTop.ts

@@ -0,0 +1,44 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <p-button type="button" [aria]="{'aria-haspopup': 'dialog'}" (click)="onClick()">
+        Open Flyout
+      </p-button>
+
+      <p-flyout [open]="open" [aria]="{'aria-label': 'Some Heading'}" (dismiss)="onDismiss()">
+        <p-heading slot="header" size="large" tag="h2">
+          Some Heading
+        </p-heading>
+        <div class="grid grid-cols-[2fr_1fr] gap-static-md items-start">
+          <div class="sticky top-[calc(var(--p-flyout-sticky-top,0)+16px)] p-static-md bg-surface">
+            Some sticky element within content relying on --p-flyout-sticky-top
+          </div>
+          <div>
+            <p-text>
+              Some Content Begin
+            </p-text>
+            <div class="w-[10px] h-[120vh] bg-[deeppink]"></div>
+            <p-text>
+              Some Content End
+            </p-text>
+          </div>
+        </div>
+      </p-flyout>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {
+  open = false;
+
+  onClick() {
+    this.open = true;
+  }
+  onDismiss() {
+    this.open = false;
+  }
+}

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

@@ -0,0 +1,128 @@
+# p-flyout
+
+The `p-flyout` is a overlay from the left or right side of the screen. It is commonly used as a temporary workspace that allows users to complete tasks without navigating to a new page or as a mobile navigation.
+
+It is a controlled component. This grants flexible control over the flyout's behavior especially whether it should stay open after user interaction like submission of a form.
+
+> **Scroll-lock**
+>
+> This component sets `overflow: hidden` on the body when opened in order to prevent background scrolling.
+>
+> This doesn't work completely reliable under iOS but is the most stable solution.
+>
+> Feel free to address this issue in an Open Source PR, if you can provide a better solution.
+>
+> **[Current implementation](https://github.com/porsche-design-system/porsche-design-system/blob/main/packages/components/src/utils/setScrollLock.ts)**
+
+## Usage
+
+### Do:
+
+- Use a Flyout as a temporary workspace that allows users to complete tasks without navigating to a new page.
+- Use a Flyout for mobile navigation.
+- Adjust Flyout size and alignment with the grid.
+- Use the sticky header for a descriptive heading & optional sub-heading.
+- Use the sticky footer for a call to action.
+- Use the sub-footer slot for additional or less important information such as legals or faqs.
+- Follow button order and positioning guidelines.
+- Use feedback banner for any feedback related to the request.
+
+### Don't:
+
+- Don't use to many actions in the sticky footer or header.
+- Don't put important information in the sub-footer slot.
+- Don't use fullscreen Flyout's on desktop.
+- Don't launch a Flyout within a Flyout.
+
+## Accessibility support
+
+The `Flyout` 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. |
+
+#### Internal **ARIA** that is managed by the component:
+
+| ARIA | Usage |
+| --- | --- |
+| `aria-label="STRING"` | Defines the accessible name if no `aria` property is provided, uses the contents of the header slot and falls back to a fixed name. |
+
+## Development considerations
+
+To inform users that the trigger button opens a `dialog`, set `aria-haspopup` on the trigger using the `aria` property. Provide the dialog title through the `header` slot or the flyout `aria` property.
+
+### 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 when opening the flyout.
+- **Do** ensure a meaningful title is available via the `header` slot or `aria` property.
+- **Don't** add raw host-level ARIA attributes as a workaround.
+- **Don't** use unclear trigger copy like "Menu" when the flyout purpose is not obvious.
+
+## API
+
+### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `aria` | `FlyoutAriaAttribute` | `undefined` | Sets ARIA attributes on the flyout dialog element for improved screen reader accessibility. |
+| `backdrop` | `'blur'` `'shading'` | `'blur'` | Sets the backdrop style. Use `blur` when background content is irrelevant; use `shading` when users still need visual context. |
+| `background` | `'canvas'` `'surface'` | `'canvas'` | Sets the background color of the flyout panel (`canvas` or `surface`). |
+| `disableBackdropClick` | `boolean` | `false` | When enabled, clicking the backdrop will not close the flyout. |
+| `footerBehavior` | `'sticky'` `'fixed'` | `'sticky'` | Controls footer behavior. `fixed` keeps it anchored at the bottom; `sticky` pins it only when content overflows. |
+| `fullscreen` | `boolean`<br>`BreakpointCustomizable<boolean>` | `false` | If true the flyout stretches to the full viewport width with squared corners. Useful for smaller viewports where the flyout would otherwise fill the screen but still show rounded corners. |
+| `open` _(required)_ | `boolean` | `false` | Controls whether the flyout panel is visible. |
+| `position` | `'start'` `'end'` | `'end'` | Sets the side the flyout slides in from — `start` for left or `end` for right in LTR layouts. |
+
+### Events
+
+| Event | Type | Description |
+| --- | --- | --- |
+| `dismiss` | `CustomEvent<void>` | Emitted when the user closes the flyout via the close button, backdrop click, or Escape key. |
+| `motionHiddenEnd` | `CustomEvent<FlyoutMotionHiddenEndEventDetail>`<br>`TransitionEvent` | Emitted after the flyout's close transition completes and the panel is fully hidden. |
+| `motionVisibleEnd` | `CustomEvent<FlyoutMotionVisibleEndEventDetail>`<br>`TransitionEvent` | Emitted after the flyout's open transition completes and the panel is fully visible. |
+
+### 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.
+
+### Slots
+
+| Slot | Required | Allowed tag names | Description |
+| --- | --- | --- | --- |
+| `header` | no | — | Renders a sticky header section above the content area. |
+| _(default)_ | no | — | Default slot for the main content. |
+| `footer` | no | — | Shows a sticky footer section, flowing under the content area when scrollable. |
+| `sub-footer` | no | — | Renders additional content below the footer, such as legal information or FAQs. It appears when the flyout has enough space or when the user scrolls to the end. |
+
+### CSS Variables
+
+| CSS Variable | Default | Description |
+| --- | --- | --- |
+| `--p-flyout-width` | `auto` | Width of the flyout. |
+| `--p-flyout-sticky-top` | — | @experimental Exposes the header's height as a read-only CSS variable, set automatically by the component. Slotted sticky content can use this value to offset their top position correctly. |
+| `--ref-p-flyout-pt` | — | Exposes the internally used padding-top of the Flyout as read only CSS variable. When slotting e.g. a media container, this variable can be used to stretch the element to the top of the Flyout. |
+| `--ref-p-flyout-pb` | — | Exposes the internally used padding-bottom of the Flyout as read only CSS variable. When slotting e.g. a media container, this variable can be used to stretch the element to the bottom of the Flyout. |
+| `--ref-p-flyout-px` | — | Exposes the internally used padding-inline of the Flyout as read only CSS variable. When slotting e.g. a media container, this variable can be used to stretch the element to the full horizontal size of the Flyout. |
+
+## Examples
+
+| Example | When to use | File |
+| --- | --- | --- |
+| Default | Minimal default configuration. | [./examples/Default.ts](./examples/Default.ts) |
+| Sticky content with Custom CSS Property (Experimental) | In order to display some sticky element within the flyout content you can use the experimental `--p-flyout-sticky-top` CSS custom property to account for the height of the header. | [./examples/StickyTop.ts](./examples/StickyTop.ts) |
+| Flyout Form | The following example demonstrates how a form can be used within a flyout component: | [./examples/Form.ts](./examples/Form.ts) |
+| Custom Styling | The Flyout exposes read-only CSS Variables (prefixed with `--ref-`). | [./examples/CustomStyling.ts](./examples/CustomStyling.ts) |

package/skill/references/components/p-heading/examples/Color.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-heading tag="h3" color="inherit" class="text-[deeppink]">
+        The quick brown fox jumps over the lazy dog
+      </p-heading>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

package/skill/references/components/p-heading/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-heading>
+        The quick brown fox jumps over the lazy dog
+      </p-heading>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

package/skill/references/components/p-heading/examples/Semantics.ts

@@ -0,0 +1,21 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <p-heading tag="h3">
+        The quick brown fox jumps over the lazy dog
+      </p-heading>
+
+      <p-heading>
+        <h3>
+          The quick brown fox jumps over the lazy dog
+        </h3>
+      </p-heading>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}