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

package/skills/pds-knowledge-react/references/components/p-crest/p-crest.md

@@ -0,0 +1,69 @@
+# p-crest
+
+The `p-crest` gives the Porsche brand a distinctive look, sets it apart from others within the overall external image and represents the quality of the product.
+
+> **Usage hint**
+>
+> This component shall only be used on viewports below 480px (breakpoint "S"). Otherwise, [p-wordmark](../p-wordmark/p-wordmark.md) has to be used.
+
+You can use native `click`, `focus`, `focusin`, `blur` and `focusout` events on the `p-crest`.
+
+## Usage
+
+### Do:
+
+- Use the [Wordmark](../p-wordmark/p-wordmark.md) as the main brand identifier.
+- Use the crest only as an additional small brand identifier (e.g., within contact cards).
+- Switch from the wordmark to the crest on small viewports below 480px (automatically implemented in global navigation and footer).
+
+### Don't:
+
+- Use the crest as the primary brand identifier by default.
+
+---
+
+## Related Components
+
+- [Wordmark](../p-wordmark/p-wordmark.md)
+
+## Accessibility support
+
+### ARIA enhancements
+
+#### External **ARIA** provided by the `aria` property:
+
+| ARIA | Usage |
+| --- | --- |
+| `aria-label` | Defines a string value that labels the interactive element. |
+| `aria-current` | Exposes the current state of the link. |
+| `aria-haspopup` | Defines that the link opens a popup (e.g. `dialog`). |
+
+## Development considerations
+
+### Common do's and don'ts
+
+- **Do** pass ARIA attributes through the `aria` prop when the crest is linked.
+- **Do** provide a descriptive `aria-label` for linked crests, for example "Porsche home".
+- **Don't** add native `aria-*` attributes directly on the component host.
+
+## Integration examples
+
+See [accessibility integration examples](./accessibility.md) for paired anti-pattern and recommended implementations.
+
+## API
+
+### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `aria` | `CrestAriaAttribute` | `undefined` | Sets ARIA attributes on the anchor element to improve accessibility when the crest is used as a link. |
+| `href` | `string` | `undefined` | When set, renders the crest as an anchor element navigating to this URL when clicked. |
+| `target` | `'_self'` `'_blank'` `'_parent'` `'_top'` `'string'` | `'_self'` | Specifies where to open the linked URL (e.g. `_self`, `_blank`). Only applies when `href` is set. |
+
+## Examples
+
+| Example | When to use | File |
+| --- | --- | --- |
+| Default | Minimal default configuration. | [./examples/Default.tsx](./examples/Default.tsx) |
+| Link | The Porsche Crest will be rendered as `<a>`-tag as soon as an `href` is provided. | [./examples/Link.tsx](./examples/Link.tsx) |
+| Custom clickable/focusable area | Sometimes it may be useful to enlarge the clickable/focusable area of the Porsche Crest. | [./examples/CustomClickableArea.tsx](./examples/CustomClickableArea.tsx) |

package/skills/pds-knowledge-react/references/components/p-display/examples/Color.tsx

@@ -0,0 +1,12 @@
+import React from 'react';
+import { PDisplay } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PDisplay tag="h3" color="inherit" className="text-[deeppink]">
+        The quick brown fox jumps over the lazy dog
+      </PDisplay>
+    </>
+  )
+}

package/skills/pds-knowledge-react/references/components/p-display/examples/Default.tsx

@@ -0,0 +1,12 @@
+import React from 'react';
+import { PDisplay } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PDisplay>
+        The quick brown fox jumps over the lazy dog
+      </PDisplay>
+    </>
+  )
+}

package/skills/pds-knowledge-react/references/components/p-display/examples/Semantics.tsx

@@ -0,0 +1,18 @@
+import React from 'react';
+import { PDisplay } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PDisplay tag="h3">
+        The quick brown fox jumps over the lazy dog
+      </PDisplay>
+
+      <PDisplay>
+        <h3>
+          The quick brown fox jumps over the lazy dog
+        </h3>
+      </PDisplay>
+    </>
+  )
+}

package/skills/pds-knowledge-react/references/components/p-display/examples/Size.tsx

@@ -0,0 +1,12 @@
+import React from 'react';
+import { PDisplay } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PDisplay tag="h3" size="inherit" className="text-[5rem]">
+        The quick brown fox jumps over the lazy dog
+      </PDisplay>
+    </>
+  )
+}

package/skills/pds-knowledge-react/references/components/p-display/examples/SizeResponsive.tsx

@@ -0,0 +1,12 @@
+import React from 'react';
+import { PDisplay } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PDisplay tag="h3" size={{'base': 'medium', 'l': 'large'}}>
+        The quick brown fox jumps over the lazy dog
+      </PDisplay>
+    </>
+  )
+}

package/skills/pds-knowledge-react/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.tsx](./examples/Default.tsx) |
+| Size | There are predefined fluid text sizes for the component which should cover most use cases. | [./examples/Size.tsx](./examples/Size.tsx) |
+| Responsive | Responsive | [./examples/SizeResponsive.tsx](./examples/SizeResponsive.tsx) |
+| Semantics | To provide more contextual HTML semantics you can either pass them with the `tag` property or directly inside a slot. | [./examples/Semantics.tsx](./examples/Semantics.tsx) |
+| Color | Predefined theme-based colors are available, but `inherit` can also be used to define a custom color. | [./examples/Color.tsx](./examples/Color.tsx) |

package/skills/pds-knowledge-react/references/components/p-divider/accessibility.md

@@ -0,0 +1,41 @@
+# p-divider accessibility integration examples
+
+## Integration examples
+
+### Divider as the only section separator
+
+#### ❌ Anti-pattern
+
+```tsx
+<PText>
+  Delivery details
+</PText>
+
+<PDivider></PDivider>
+
+<PText>
+  Payment details
+</PText>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PHeading tag="h2" size="md">
+  Delivery details
+</PHeading>
+
+<PText>
+  ...
+</PText>
+
+<PDivider></PDivider>
+
+<PHeading tag="h2" size="md">
+  Payment details
+</PHeading>
+
+<PText>
+  ...
+</PText>
+```

package/skills/pds-knowledge-react/references/components/p-divider/examples/Default.tsx

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

package/skills/pds-knowledge-react/references/components/p-divider/examples/Responsive.tsx

@@ -0,0 +1,12 @@
+import React from 'react';
+import { PDivider } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <div className="lg:flex lg:h-[150px]">
+        <PDivider direction={{'base': 'horizontal', 'l': 'vertical'}}></PDivider>
+      </div>
+    </>
+  )
+}

package/skills/pds-knowledge-react/references/components/p-divider/examples/Vertical.tsx

@@ -0,0 +1,12 @@
+import React from 'react';
+import { PDivider } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <div className="flex h-[100px]">
+        <PDivider direction="vertical"></PDivider>
+      </div>
+    </>
+  )
+}

package/skills/pds-knowledge-react/references/components/p-divider/p-divider.md

@@ -0,0 +1,53 @@
+# 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.
+
+## Integration examples
+
+See [accessibility integration examples](./accessibility.md) for paired anti-pattern and recommended implementations.
+
+## 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.tsx](./examples/Default.tsx) |
+| 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.tsx](./examples/Vertical.tsx) |
+| Responsive | You can change the divider's direction by using different major breakpoints `xs`, `s`, `m`, `l`, `xl`. | [./examples/Responsive.tsx](./examples/Responsive.tsx) |

package/skills/pds-knowledge-react/references/components/p-drilldown/accessibility.md

@@ -0,0 +1,65 @@
+# p-drilldown accessibility integration examples
+
+## Integration examples
+
+### ARIA on trigger button host vs aria prop
+
+#### ❌ Anti-pattern
+
+```tsx
+<PButton aria-haspopup="dialog">
+  Menu
+</PButton>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PButton aria={{'aria-haspopup': 'dialog'}}>
+  Vehicle menu
+</PButton>
+```
+
+### Drilldown label on component host vs aria prop
+
+#### ❌ Anti-pattern
+
+```tsx
+<PDrilldown open={true} aria-label="Navigation">
+  ...
+</PDrilldown>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PDrilldown open={true} aria={{'aria-label': 'Vehicle navigation'}}>
+  ...
+</PDrilldown>
+```
+
+### Trigger without popup semantics or context
+
+#### ❌ Anti-pattern
+
+```tsx
+<PButton>
+  Menu
+</PButton>
+
+<PDrilldown>
+  ...
+</PDrilldown>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PButton aria={{'aria-haspopup': 'dialog'}}>
+  Vehicle menu
+</PButton>
+
+<PDrilldown aria={{'aria-label': 'Vehicle navigation'}}>
+  ...
+</PDrilldown>
+```

package/skills/pds-knowledge-react/references/components/p-drilldown/examples/CustomContent.tsx

@@ -0,0 +1,164 @@
+import React from 'react';
+import { useState } from 'react';
+import { PButton, PButtonTile, PDrilldown, PDrilldownItem, PDrilldownLink, PLink, PModelSignature, type DrilldownUpdateEventDetail } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  const [activeIdentifier, setActiveIdentifier] = useState("id-1");
+  const [open, setOpen] = useState(false);
+
+  const onClick = () => {
+    setOpen(true);
+  }
+  const onUpdate = (e: CustomEvent<DrilldownUpdateEventDetail>) => {
+    setActiveIdentifier(e.detail.activeIdentifier);
+  }
+  const onDismiss = () => {
+    setOpen(false);
+  }
+
+  return (
+    <>
+      <nav aria-label="Main">
+        <PButton type="button" aria={{'aria-haspopup': 'dialog'}} onClick={onClick}>
+          Open Drilldown
+        </PButton>
+        <PDrilldown open={open} activeIdentifier={activeIdentifier} className="[--p-drilldown-grid-template:repeat(5,auto)_minmax(0,1fr)/auto]" onUpdate={onUpdate} onDismiss={onDismiss}>
+          <PDrilldownItem identifier="id-1" label="Motorsport" className="[--p-drilldown-grid-template:auto/repeat(2,minmax(0,1fr))] [--p-drilldown-gap:0px_16px]">
+            <PDrilldownItem identifier="id-1-1" label="718">
+              <PModelSignature slot="header" model="718"></PModelSignature>
+              <PButtonTile slot="button" label="Some label" description="718" weight="semi-bold" compact={true} aspectRatio={{'base': '1/1', 's': '9/16'}} className="mb-fluid-sm">
+                <img srcSet="assets/porsche-963@2x.webp 2x" src="assets/porsche-963.webp" width={636} height={847} alt="Porsche 963" />
+              </PButtonTile>
+              <PDrilldownLink href="#">
+                Some anchor
+              </PDrilldownLink>
+              <PDrilldownLink href="#">
+                Some anchor
+              </PDrilldownLink>
+              <PDrilldownLink href="#">
+                Some anchor
+              </PDrilldownLink>
+              <PDrilldownLink href="#">
+                Some anchor
+              </PDrilldownLink>
+            </PDrilldownItem>
+            <PDrilldownItem identifier="id-1-2" label="911">
+              <PModelSignature slot="header" model="911"></PModelSignature>
+              <PButtonTile slot="button" label="Some label" description="911" weight="semi-bold" compact={true} aspectRatio={{'base': '1/1', 's': '9/16'}} className="mb-fluid-sm">
+                <img srcSet="assets/porsche-963@2x.webp 2x" src="assets/porsche-963.webp" width={636} height={847} alt="Porsche 963" />
+              </PButtonTile>
+              <PDrilldownLink href="#">
+                Some anchor
+              </PDrilldownLink>
+              <PDrilldownLink href="#">
+                Some anchor
+              </PDrilldownLink>
+            </PDrilldownItem>
+            <PDrilldownLink href="#">
+              Some anchor
+            </PDrilldownLink>
+            <PDrilldownLink href="#" aria-current="page">
+              Some anchor
+            </PDrilldownLink>
+            <PDrilldownLink href="#">
+              Some anchor
+            </PDrilldownLink>
+            <PDrilldownLink href="#">
+              Some anchor
+            </PDrilldownLink>
+            <PDrilldownLink href="#">
+              Some anchor
+            </PDrilldownLink>
+            <PDrilldownLink href="#">
+              Some anchor
+            </PDrilldownLink>
+            <PDrilldownLink href="#">
+              Some anchor
+            </PDrilldownLink>
+            <PDrilldownLink href="#">
+              Some anchor
+            </PDrilldownLink>
+            <PDrilldownLink href="#">
+              Some anchor
+            </PDrilldownLink>
+          </PDrilldownItem>
+          <PDrilldownItem identifier="id-2" label="Some label">
+            <PDrilldownItem identifier="id-2-1" label="Some label">
+              <PDrilldownLink href="#">
+                Some anchor
+              </PDrilldownLink>
+              <PDrilldownLink href="#">
+                Some anchor
+              </PDrilldownLink>
+              <PDrilldownLink href="#">
+                Some anchor
+              </PDrilldownLink>
+              <PDrilldownLink href="#">
+                Some anchor
+              </PDrilldownLink>
+            </PDrilldownItem>
+            <PDrilldownItem identifier="id-2-2" label="Some label">
+              <PDrilldownLink href="#">
+                Some anchor
+              </PDrilldownLink>
+              <PDrilldownLink href="#">
+                Some anchor
+              </PDrilldownLink>
+              <PDrilldownLink href="#">
+                Some anchor
+              </PDrilldownLink>
+            </PDrilldownItem>
+            <PDrilldownLink href="#">
+              Some anchor
+            </PDrilldownLink>
+            <PDrilldownLink href="#">
+              Some anchor
+            </PDrilldownLink>
+            <PDrilldownLink href="#">
+              Some anchor
+            </PDrilldownLink>
+            <PDrilldownLink href="#">
+              Some anchor
+            </PDrilldownLink>
+          </PDrilldownItem>
+          <PDrilldownItem identifier="id-3" label="Some label">
+            <PDrilldownLink href="#">
+              Some anchor
+            </PDrilldownLink>
+            <PDrilldownLink href="#">
+              Some anchor
+            </PDrilldownLink>
+            <PDrilldownLink href="#">
+              Some anchor
+            </PDrilldownLink>
+            <PDrilldownLink href="#">
+              Some anchor
+            </PDrilldownLink>
+          </PDrilldownItem>
+          <PDrilldownItem identifier="id-4" label="Some label">
+            <PDrilldownLink href="#">
+              Some anchor
+            </PDrilldownLink>
+            <PDrilldownLink href="#">
+              Some anchor
+            </PDrilldownLink>
+            <PDrilldownLink href="#">
+              Some anchor
+            </PDrilldownLink>
+          </PDrilldownItem>
+          <PDrilldownItem identifier="id-5" label="Some label">
+            <PDrilldownLink href="#">
+              Some anchor
+            </PDrilldownLink>
+            <PDrilldownLink href="#">
+              Some anchor
+            </PDrilldownLink>
+          </PDrilldownItem>
+          <PLink href="#" variant="secondary" icon="external" className="self-end">
+            Some external anchor
+          </PLink>
+        </PDrilldown>
+      </nav>
+    </>
+  )
+}