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

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

@@ -0,0 +1,95 @@
+# p-accordion
+
+The `p-accordion` is a component that reveals or hides associated sections of content. Accordions are flexible in the context and can include other components of the Porsche Design System.
+
+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 accordions to organize and display large amounts of content in a structured and efficient way.
+- Group related content together within each accordion panel.
+- Use clear and concise headings for each accordion panel to help users quickly understand what content is included.
+- Make sure that each accordion panel is easily identifiable and distinguishable from the others.
+
+### Don't:
+
+- Don't use accordions for content that is essential or required for users to see. Users may not realize that they need to expand the accordion panel to see the content, resulting in a poor user experience.
+- Don't overuse accordions on a single page, as this can make the page feel cluttered and difficult to navigate.
+- Don't use ambiguous or confusing labels for the accordion headings, as this can make it difficult for users to understand what content is included in each panel.
+- Don't overload the accordion panels with too much content, as this can make the component feel overwhelming and difficult to use.
+- Don't add a divider on top of the first item.
+
+## Accessibility support
+
+### Keyboard
+
+| Key / state | Function |
+| --- | --- |
+| `Tab`, `Shift-Tab` | Moves focus to the next (or previous) focusable element. |
+| `Enter/Space` | When focus is on the accordion trigger, the associated panel expands or collapses. |
+
+## Development considerations
+
+### Heading hierarchy
+
+The accordion summary should be a heading element (e.g.,`p-heading` or `<h1>` to `<h6>`,) to ensure proper semantic structure and correct heading hierarchy.
+
+### Common do's and don'ts
+
+- **Do** use the `summary` slot with a heading element such as `p-heading` or native `h1`–`h6`.
+- **Do** keep heading levels sequential across multiple accordions on a page.
+- **Don't** use plain text in the summary without a semantic heading.
+
+## API
+
+### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `alignMarker` | `'start'` `'end'` | `'end'` | Positions the expand/collapse marker icon at the start or end of the summary section. |
+| `background` | `'canvas'` `'surface'` `'frosted'` `'none'` | `'none'` | Sets the background color of the accordion panel. Use `frosted` only when placed on images, videos, or gradients. |
+| `compact` | `boolean` | `undefined` | Reduces padding and spacing for a more compact layout, useful in space-constrained interfaces. |
+| `heading` _(deprecated)_ | `string` | `undefined` | @deprecated Will be removed in the next major release. Use the `summary` slot instead. Sets the heading text within the summary section. |
+| `headingTag` _(deprecated)_ | `'h1'` `'h2'` `'h3'` `'h4'` `'h5'` `'h6'` | `'h2'` | @deprecated Will be removed in the next major release. Use the `summary` slot instead. Sets the heading tag for proper semantic structure within the page. |
+| `indent` | `boolean`<br>`BreakpointCustomizable<boolean>` | `false` | Indents the slotted content to be vertically aligned with the text of the summary section. |
+| `open` | `boolean` | `undefined` | Controls whether the accordion is open or closed. |
+| `size` _(deprecated)_ | `'small'` `'medium'`<br>`BreakpointCustomizable<AccordionSize>` | `'small'` | @deprecated Will be removed in the next major release. Use the `summary` slot instead. Controls the heading size in the summary section (only applies when using the `heading` prop or `heading` slot). |
+| `sticky` _(experimental)_ | `boolean` | `undefined` | @experimental Makes the summary section sticky at the top while scrolling. Only works with `background="canvas"` or `background="surface"`. Not compatible with `summary-before` or `summary-after` slots. |
+
+### Events
+
+| Event | Type | Description |
+| --- | --- | --- |
+| `update` | `CustomEvent<AccordionUpdateEventDetail>`<br>`{ open: boolean }` | Emitted when the user toggles the accordion open or closed, with the new open state in the event detail. |
+
+### Controlled properties
+
+- `open` — a controlled prop: the component does **not** update it itself. Handle the `update` event and assign the new value to `open` yourself, or the change will not take effect.
+
+### Slots
+
+| Slot | Required | Allowed tag names | Description |
+| --- | --- | --- | --- |
+| `summary` | no | — | Content for the accordion's summary section. Clicking toggles the accordion open and closed. |
+| `summary-before` | no | — | Content or interactive elements placed before the accordion's summary section. |
+| `summary-after` | no | — | Content or interactive elements placed after the accordion's summary section. |
+| `heading` _(deprecated)_ | no | — | Content for the accordion's heading section. Clicking toggles the accordion open and closed. |
+| _(default)_ | no | — | Main content displayed when the accordion is expanded. |
+
+### CSS Variables
+
+| CSS Variable | Default | Description |
+| --- | --- | --- |
+| `--p-accordion-summary-top` | `0px` | Controls the sticky top position when `sticky` is enabled. |
+| `--p-accordion-px` | `16px` | Horizontal padding of the accordion. |
+| `--p-accordion-py` | `16px` | Vertical padding of the accordion. |
+
+## Examples
+
+| Example | When to use | File |
+| --- | --- | --- |
+| Default | Minimal default configuration. | [./examples/Default.tsx](./examples/Default.tsx) |
+| Sticky summary | The summary can be made sticky by adding the experimental property `sticky` to the `p-accordion` tag. | [./examples/StickySummary.tsx](./examples/StickySummary.tsx) |
+| Interactive elements in summary | The summary section supports interactive elements via the `slot="summary-before"` and `slot="summary-after"` attributes. | [./examples/InteractiveElementsInSummary.tsx](./examples/InteractiveElementsInSummary.tsx) |

package/skill/references/components/p-ai-tag/examples/Default.tsx

@@ -0,0 +1,10 @@
+import React from 'react';
+import { PAiTag } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PAiTag></PAiTag>
+    </>
+  )
+}

package/skill/references/components/p-ai-tag/examples/WithinCheckbox.tsx

@@ -0,0 +1,30 @@
+import React from 'react';
+import { PAiTag, PCheckbox, PFieldset, PText } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PFieldset label="Pick your favorite Fruits" labelSize="small" className="flex flex-col gap-static-sm">
+        <PText className="-mt-static-md mb-static-sm">
+          Slotted description with optional link
+        </PText>
+        <div className="flex flex-col gap-static-sm">
+          <PCheckbox>
+            <span slot="label">
+              Banana
+              <PAiTag variant="generated" className="ms-static-sm"></PAiTag>
+            </span>
+          </PCheckbox>
+          <PCheckbox label="Apple"></PCheckbox>
+          <PCheckbox checked={true}>
+            <span slot="label">
+              Melon
+              <PAiTag variant="abbreviation" className="ms-static-sm"></PAiTag>
+            </span>
+          </PCheckbox>
+          <PCheckbox label="Grapefruit"></PCheckbox>
+        </div>
+      </PFieldset>
+    </>
+  )
+}

package/skill/references/components/p-ai-tag/examples/WithinFormLabel.tsx

@@ -0,0 +1,37 @@
+import React from 'react';
+import { PAiTag, POptgroup, PSelect, PSelectOption } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PSelect name="options" description="Some description">
+        <span slot="label">
+          Pick your favorite Fruits
+          <PAiTag variant="abbreviation" className="ms-static-sm"></PAiTag>
+        </span>
+        <POptgroup label="Some optgroup label 1">
+          <PSelectOption value="a">
+            Option A
+          </PSelectOption>
+          <PSelectOption value="b">
+            Option B
+          </PSelectOption>
+          <PSelectOption value="c">
+            Option C
+          </PSelectOption>
+        </POptgroup>
+        <POptgroup label="Some optgroup label 2">
+          <PSelectOption value="d">
+            Option D
+          </PSelectOption>
+          <PSelectOption value="e">
+            Option E
+          </PSelectOption>
+          <PSelectOption value="f">
+            Option F
+          </PSelectOption>
+        </POptgroup>
+      </PSelect>
+    </>
+  )
+}

package/skill/references/components/p-ai-tag/examples/WithinImage.tsx

@@ -0,0 +1,13 @@
+import React from 'react';
+import { PAiTag } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <div className="relative inline-block rounded-lg overflow-hidden">
+        <img src="assets/ai-tag-image.jpg" alt="AI modified image" className="block w-[300px] h-[300px] object-cover" />
+        <PAiTag variant="modified" className="absolute bottom-static-sm end-static-sm scheme-dark"></PAiTag>
+      </div>
+    </>
+  )
+}

package/skill/references/components/p-ai-tag/examples/WithinInputSearch.tsx

@@ -0,0 +1,12 @@
+import React from 'react';
+import { PAiTag, PInputSearch } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PInputSearch label="What's your favorite Fruit" description="Search for fruits" name="search">
+        <PAiTag slot="end" variant="abbreviation"></PAiTag>
+      </PInputSearch>
+    </>
+  )
+}

package/skill/references/components/p-ai-tag/examples/WithinRadioGroup.tsx

@@ -0,0 +1,29 @@
+import React from 'react';
+import { PAiTag, PHeading, PRadioGroup, PRadioGroupOption } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PHeading size="small" tag="h3">
+        Pick your favorite Fruits
+      </PHeading>
+
+      <PRadioGroup label="Some Label" name="fruit" value="banana" className="mt-static-sm">
+        <PRadioGroupOption value="banana">
+          <span slot="label">
+            Banana
+            <PAiTag variant="generated" className="ms-static-sm"></PAiTag>
+          </span>
+        </PRadioGroupOption>
+        <PRadioGroupOption value="apple" label="Apple"></PRadioGroupOption>
+        <PRadioGroupOption value="melon">
+          <span slot="label">
+            Melon
+            <PAiTag variant="abbreviation" className="ms-static-sm"></PAiTag>
+          </span>
+        </PRadioGroupOption>
+        <PRadioGroupOption value="grapefruit" label="Grapefruit"></PRadioGroupOption>
+      </PRadioGroup>
+    </>
+  )
+}

package/skill/references/components/p-ai-tag/examples/WithinTable.tsx

@@ -0,0 +1,91 @@
+import React from 'react';
+import { PAiTag, PHeading, PTable, PTableBody, PTableCell, PTableHead, PTableHeadCell, PTableHeadRow, PTableRow } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <div className="w-full">
+        <PTable>
+          <PHeading slot="caption" size="large" tag="h3">
+            Some slotted caption
+          </PHeading>
+          <PTableHead>
+            <PTableHeadRow>
+              <PTableHeadCell sort={{'id': 'model', 'active': 'true', 'direction': 'desc'}}>
+                Model
+              </PTableHeadCell>
+              <PTableHeadCell>
+                Date
+              </PTableHeadCell>
+              <PTableHeadCell>
+                Purchase Intention
+              </PTableHeadCell>
+              <PTableHeadCell>
+                <span className="inline-flex items-center gap-static-sm">
+                  Status
+                  <PAiTag variant="abbreviation"></PAiTag>
+                </span>
+              </PTableHeadCell>
+              <PTableHeadCell>
+                Lead ID
+              </PTableHeadCell>
+            </PTableHeadRow>
+          </PTableHead>
+          <PTableBody>
+            <PTableRow>
+              <PTableCell>
+                718 Cayman
+              </PTableCell>
+              <PTableCell>
+                23.06.2021
+              </PTableCell>
+              <PTableCell>
+                New Car
+              </PTableCell>
+              <PTableCell>
+                Won
+              </PTableCell>
+              <PTableCell>
+                0000824402
+              </PTableCell>
+            </PTableRow>
+            <PTableRow>
+              <PTableCell>
+                Panamera 4S
+              </PTableCell>
+              <PTableCell>
+                15.03.2023
+              </PTableCell>
+              <PTableCell>
+                Used Car
+              </PTableCell>
+              <PTableCell>
+                Lost
+              </PTableCell>
+              <PTableCell>
+                0000824408
+              </PTableCell>
+            </PTableRow>
+            <PTableRow>
+              <PTableCell>
+                911 Carrera S
+              </PTableCell>
+              <PTableCell>
+                28.08.2025
+              </PTableCell>
+              <PTableCell>
+                New Car
+              </PTableCell>
+              <PTableCell>
+                Won
+              </PTableCell>
+              <PTableCell>
+                0000824409
+              </PTableCell>
+            </PTableRow>
+          </PTableBody>
+        </PTable>
+      </div>
+    </>
+  )
+}

package/skill/references/components/p-ai-tag/examples/WithinText.tsx

@@ -0,0 +1,14 @@
+import React from 'react';
+import { PAiTag, PText } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PText>
+        This content was generated using artificial intelligence (AI). AI can be a powerful tool for creating content, but it's important to be transparent about its use. By including an AI tag, we can inform users that this content may have been modified or generated by AI, helping to build trust and provide context for the information presented.
+        <PAiTag variant="modified" className="align-bottom"></PAiTag>
+         This is some additional text to show how the AI tag can be used within a text component. The AI tag can be used to indicate that certain content has been modified or generated by AI, providing transparency to users.
+      </PText>
+    </>
+  )
+}

package/skill/references/components/p-ai-tag/p-ai-tag.md

@@ -0,0 +1,47 @@
+# p-ai-tag
+
+`p-ai-tag` is used to indicate AI-generated or AI-modified content. It displays a localized and legally compliant AI label text (abbreviated or as long-form) combined with an icon.
+
+## Usage
+
+Use the AI tag to indicate that content has been generated or assisted by artificial intelligence.
+
+The following segment provides instructions for designers and developers regarding the appropriate utilization of this component in various situations.
+
+### Do:
+
+- Use to indicate AI-generated or AI-assisted content.
+- Use the appropriate `locale` to match the user's language.
+- Use the `abbreviation` variant for compact contexts where space is limited.
+- Use the `generated` or `modified` variant when a full label improves clarity.
+
+### Don't:
+
+- Don't use as a general-purpose tag — use `p-tag` instead.
+- Don't use for non-AI-related labeling or categorization.
+
+## Accessibility support
+
+For the `abbreviation` variant, the component uses an `<abbr>` element so the full “artificial intelligence” term is available as the expansion.
+
+## API
+
+### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `locale` | `'bg_BG'` `'bs_BA'` `'cs_CZ'` `'da_DK'` `'de_DE'` `'el_GR'` `'en_CY'` `'en_GB'` `'en_US'` `'es_ES'` `'et_EE'` `'fi_FI'` `'fr_FR'` `'he_IL'` `'hr_HR'` `'hu_HU'` `'is_IS'` `'it_IT'` `'lt_LT'` `'lv_LV'` `'me_ME'` `'mk_MK'` `'mt_MT'` `'nb_NO'` `'nl_NL'` `'pl_PL'` `'pt_PT'` `'ro_RO'` `'ru_RU'` `'sk_SK'` `'sl_SI'` `'sr_RS'` `'sv_SE'` `'tr_TR'` `'uk_UA'` | `'en_US'` | Locale for the AI text (ISO format, e.g. "de_DE"). |
+| `variant` | `'abbreviation'` `'generated'` `'modified'` | `'generated'` | Variant to display: 'abbreviation' (e.g. "AI"), 'generated' (e.g. "AI-generated"), or 'modified' (e.g. "AI-modified"). |
+
+## Examples
+
+| Example | When to use | File |
+| --- | --- | --- |
+| Default | Minimal default configuration. | [./examples/Default.tsx](./examples/Default.tsx) |
+| Within Checkbox | The `p-ai-tag` can be used inline with other form components. | [./examples/WithinCheckbox.tsx](./examples/WithinCheckbox.tsx) |
+| Within Radio Group | The `p-ai-tag` can also be placed within the slotted label of a `p-radio-button-wrapper` to indicate AI-related content for individual radio options. | [./examples/WithinRadioGroup.tsx](./examples/WithinRadioGroup.tsx) |
+| Within Form Label | The `p-ai-tag` can be placed within a `label` of a `p-select` (or any other form component) to indicate AI-related content for selected options. | [./examples/WithinFormLabel.tsx](./examples/WithinFormLabel.tsx) |
+| Within Input Search | The `p-ai-tag` can be placed in the `end` slot of a `p-input-search` to indicate that the search results are AI-powered. | [./examples/WithinInputSearch.tsx](./examples/WithinInputSearch.tsx) |
+| Within Text | The `p-ai-tag` can be placed inline within a `p-text` to indicate that the surrounding text content is AI-related. | [./examples/WithinText.tsx](./examples/WithinText.tsx) |
+| Within Image | The `p-ai-tag` can be positioned as an overlay on images to indicate that the image content has been generated or modified by AI. | [./examples/WithinImage.tsx](./examples/WithinImage.tsx) |
+| Within Table | The `p-ai-tag` can sit inline in a `p-table-head-cell` next to the column title — for example on a **Status** column when that data is AI-assisted. | [./examples/WithinTable.tsx](./examples/WithinTable.tsx) |

package/skill/references/components/p-banner/examples/Customization.tsx

@@ -0,0 +1,35 @@
+import React from 'react';
+import { useState } from 'react';
+import { PBanner, PButton, PHeading, PLinkPure, PText } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  const [open, setOpen] = useState(false);
+
+  const onClick = () => {
+    setOpen(true);
+  }
+  const onDismiss = () => {
+    setOpen(false);
+  }
+
+  return (
+    <>
+      <PButton type="button" onClick={onClick}>
+        Open Banner
+      </PButton>
+
+      <PBanner open={open} className="[--p-banner-top:8px] [--p-banner-bottom:8px] [--p-banner-inset-x:8px] [--p-banner-max-w:70ch]" onDismiss={onDismiss}>
+        <PHeading slot="heading" size="sm" weight="semibold">
+          Some heading
+        </PHeading>
+        <PText slot="description">
+          Some description. You can also add inline 
+          <PLinkPure href="https://porsche.com" icon="none" underline={true}>
+            links
+          </PLinkPure>
+           to route to another page.
+        </PText>
+      </PBanner>
+    </>
+  )
+}

package/skill/references/components/p-banner/examples/Default.tsx

@@ -0,0 +1,24 @@
+import React from 'react';
+import { useState } from 'react';
+import { PBanner, PButton } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  const [open, setOpen] = useState(false);
+
+  const onClick = () => {
+    setOpen(true);
+  }
+  const onDismiss = () => {
+    setOpen(false);
+  }
+
+  return (
+    <>
+      <PButton type="button" onClick={onClick}>
+        Open Banner
+      </PButton>
+
+      <PBanner open={open} heading="Some Heading" headingTag="h3" description="Some Description" onDismiss={onDismiss}></PBanner>
+    </>
+  )
+}

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

@@ -0,0 +1,92 @@
+# p-banner
+
+The `p-banner` component provides action-based feedback messages (e.g. after performing a task) or to convey informational and/or critical notification like some site related topics.
+
+Review the [notification decision tree](https://designsystem.porsche.com/patterns/notifications/decision-tree) to determine which notification component is best for a particular scenario.
+
+For more information about the Usage of the `p-banner` checkout the [Notification](https://designsystem.porsche.com/patterns/notifications/introduction) page.
+
+## Accessibility support
+
+### Keyboard
+
+| Key / state | Function |
+| --- | --- |
+| `ESC` | Closes the Banner. |
+| `Tab`, `Shift-Tab` | Moves focus to the next focusable element. |
+| `focus` | Moves focus automatically to the close button. |
+
+### ARIA enhancements
+
+#### Internal **ARIA** that is managed by the component:
+
+| ARIA | Usage |
+| --- | --- |
+| `role="status"` | When content is populated or changed in `state="info"`, the component announces it unobtrusively. |
+| `role="alert"` | When content is populated or changed in `state="warning/error"`, the component announces it immediately. |
+| `aria-label="STRING"` | References the accessible name. |
+
+## Development considerations
+
+### Focus handling
+
+To support **keyboard navigation**, please take care of correct **focus handling** after closing the `Banner` with `ESC` or `Enter` key: The trigger element (e.g. a button) which has opened the `Banner` must receive focus state again after the `Banner` is closed. This is important to keep focus order consistent.
+
+### ARIA live announcements
+
+The `Banner` component uses `role="status"` and `role="alert"` to announce **content changes** for assistive technologies, but only if the component is **pre-rendered** and the content is added dynamically.
+
+### Common do's and don'ts
+
+- **Do** pre-render the banner in the DOM and update its content when showing feedback.
+- **Do** provide meaningful `heading` and `description` text for warnings and errors.
+- **Do** return focus to the trigger or at a logical place after the banner is dismissed.
+- **Don't** mount the entire banner only at the moment it should be announced.
+
+## API
+
+### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `description` | `string` | `''` | Sets the supporting description text shown below the heading. |
+| `dismissButton` | `boolean` | `true` | Shows a dismiss button so the user can manually close the banner. |
+| `heading` | `string` | `''` | Sets the heading text displayed at the top of the banner. |
+| `headingTag` | `'h1'` `'h2'` `'h3'` `'h4'` `'h5'` `'h6'` | `'h5'` | Sets the HTML heading tag (e.g. h2, h3) to maintain correct document structure for the heading. |
+| `open` _(required)_ | `boolean` | `false` | Controls whether the banner is visible. Set to `true` to show it and `false` to hide it. |
+| `position` | `'top'` `'bottom'`<br>`BreakpointCustomizable<BannerPosition>` | `{"base":"bottom","s":"top"}` | Sets the position of the banner on screen — `top` or `bottom`. Supports responsive breakpoint values. |
+| `state` | `'info'` `'success'` `'warning'` `'error'` | `'info'` | Sets the visual state of the banner — controls the icon and color scheme (`info`, `warning`, `error`, `success`). |
+
+### Events
+
+| Event | Type | Description |
+| --- | --- | --- |
+| `dismiss` | `CustomEvent<void>` | Emitted when the user closes the banner via the dismiss button or Escape key. |
+
+### 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 |
+| --- | --- | --- | --- |
+| `heading` | no | — | Defines the heading of the banner. Can be used as an alternative to the `heading` prop for rich content. |
+| _(default)_ | no | — | Default slot for the banner description content. |
+| `description` _(deprecated)_ | no | — | Deprecated: Use the default slot instead. |
+
+### CSS Variables
+
+| CSS Variable | Default | Description |
+| --- | --- | --- |
+| `--p-banner-max-w` | `100ch` | Defines the maximum width of the Banner. |
+| `--p-banner-top` | `56px` | Defines the distance from the top of the viewport. Only takes effect when the `position` property is set to `top` (at the respective breakpoint). |
+| `--p-banner-bottom` | `56px` | Defines the distance from the bottom of the viewport. Only takes effect when the `position` property is set to `bottom` (at the respective breakpoint). |
+| `--p-banner-inset-x` | `max(22px, 10.625vw - 12px)` | Defines the horizontal offset of the Banner from the edges of the viewport. |
+
+## Examples
+
+| Example | When to use | File |
+| --- | --- | --- |
+| Default | Minimal default configuration. | [./examples/Default.tsx](./examples/Default.tsx) |
+| Customization | Rich content for `heading` and `description` can be provided via named slots. | [./examples/Customization.tsx](./examples/Customization.tsx) |

package/skill/references/components/p-button/examples/Default.tsx

@@ -0,0 +1,12 @@
+import React from 'react';
+import { PButton } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PButton>
+        Some label
+      </PButton>
+    </>
+  )
+}

package/skill/references/components/p-button/examples/Form.tsx

@@ -0,0 +1,28 @@
+import React from 'react';
+import { PButton, PText } from '@porsche-design-system/components-react';
+import { type FormEvent, useState } from 'react';
+
+export const Example = () => {
+  const [lastSubmittedData, setLastSubmittedData] = useState('none');
+
+  const handleSubmit = (e: FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    const formData = Array.from(new FormData(e.currentTarget, (e.nativeEvent as SubmitEvent).submitter).entries())[0];
+    setLastSubmittedData(formData.join('=') || 'none');
+  };
+
+  return (
+    <>
+      <form onSubmit={handleSubmit} className="flex gap-fluid-sm">
+        <PButton name="option" value="A" type="submit">
+          Button A
+        </PButton>
+        <PButton name="option" value="B" type="submit">
+          Button B
+        </PButton>
+      </form>
+
+      <PText>Last submitted data: {lastSubmittedData}</PText>
+    </>
+  );
+};

package/skill/references/components/p-button/examples/FormAttribute.tsx

@@ -0,0 +1,31 @@
+import React from 'react';
+import { PButton, PText, PTextarea } from '@porsche-design-system/components-react';
+import { type FormEvent, useState } from 'react';
+
+export const Example = () => {
+  const [lastSubmittedData, setLastSubmittedData] = useState('none');
+
+  const handleSubmit = (e: FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    const formData = new FormData(e.currentTarget);
+    setLastSubmittedData((formData.get('some-name') as string) || 'none');
+  };
+
+  return (
+    <>
+      <form onSubmit={handleSubmit} id="some-form">
+        <PTextarea name="some-name" label="Some Label"></PTextarea>
+      </form>
+      <div className="flex gap-fluid-sm mt-fluid-sm">
+        <PButton type="submit" form="some-form">
+          Submit
+        </PButton>
+        <PButton type="reset" form="some-form">
+          Reset
+        </PButton>
+      </div>
+
+      <PText>Last submitted data: {lastSubmittedData}</PText>
+    </>
+  );
+};