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

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

@@ -0,0 +1,54 @@
+import React from 'react';
+import { PButton, PCheckbox, PFlyout, PHeading, PText, PTextarea } from '@porsche-design-system/components-react';
+import { type FormEvent, useCallback, useState } from 'react';
+
+export const Example = () => {
+  const [isFlyoutOpen, setIsFlyoutOpen] = useState<boolean>(false);
+  const [checkboxValue, setCheckboxValue] = useState('none');
+  const [textareaValue, setTextareaValue] = useState('none');
+
+  const onOpen = useCallback(() => {
+    setIsFlyoutOpen(true);
+  }, []);
+  const onDismiss = useCallback(() => {
+    setIsFlyoutOpen(false);
+  }, []);
+
+  const onSubmit = (e: FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    const formData = new FormData(e.currentTarget);
+    setCheckboxValue(formData.get('some-checkbox')?.toString() || 'none');
+    setTextareaValue(formData.get('some-textarea')?.toString() || 'none');
+  };
+
+  return (
+    <>
+      <PButton type="button" aria={{ 'aria-haspopup': 'dialog' }} onClick={onOpen}>
+        Open Flyout
+      </PButton>
+      <PFlyout open={isFlyoutOpen} onDismiss={onDismiss} aria={{ 'aria-label': 'Some Heading' }}>
+        <PHeading slot="header" size="large" tag="h2">
+          Some Heading
+        </PHeading>
+        <form id="some-form" onSubmit={onSubmit}>
+          <PCheckbox name="some-checkbox" label="Some Label"></PCheckbox>
+          <PTextarea name="some-textarea" label="Some Label"></PTextarea>
+        </form>
+        <PButton slot="footer" type="submit" form="some-form">
+          Submit
+        </PButton>
+        <PButton slot="footer" type="reset" variant="secondary" form="some-form">
+          Reset
+        </PButton>
+        <PText slot="sub-footer">
+          Last submitted data:
+          <br />
+          <br />
+          checkbox: {checkboxValue}
+          <br />
+          textarea: {textareaValue}
+        </PText>
+      </PFlyout>
+    </>
+  );
+};

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

@@ -0,0 +1,42 @@
+import React from 'react';
+import { useState } from 'react';
+import { PButton, PFlyout, PHeading, 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" aria={{'aria-haspopup': 'dialog'}} onClick={onClick}>
+        Open Flyout
+      </PButton>
+
+      <PFlyout open={open} aria={{'aria-label': 'Some Heading'}} onDismiss={onDismiss}>
+        <PHeading slot="header" size="large" tag="h2">
+          Some Heading
+        </PHeading>
+        <div className="grid grid-cols-[2fr_1fr] gap-static-md items-start">
+          <div className="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>
+            <PText>
+              Some Content Begin
+            </PText>
+            <div className="w-[10px] h-[120vh] bg-[deeppink]"></div>
+            <PText>
+              Some Content End
+            </PText>
+          </div>
+        </div>
+      </PFlyout>
+    </>
+  )
+}

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.tsx](./examples/Default.tsx) |
+| 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.tsx](./examples/StickyTop.tsx) |
+| Flyout Form | The following example demonstrates how a form can be used within a flyout component: | [./examples/Form.tsx](./examples/Form.tsx) |
+| Custom Styling | The Flyout exposes read-only CSS Variables (prefixed with `--ref-`). | [./examples/CustomStyling.tsx](./examples/CustomStyling.tsx) |

package/skill/references/components/p-heading/examples/Color.tsx

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

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

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

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

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

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

@@ -0,0 +1,78 @@
+# p-heading
+
+`p-heading` 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-heading is used to highlight and specify heading styling and hierarchy
+
+### Do:
+
+- Use p-heading styles to clearly mark section titles and subsections.
+- Align headings with the grid to maintain visual rhythm.
+- Use heading-xx-large for primary sections; scale down for subsections.
+- Pair each heading with a text style one or two steps smaller (e.g. heading-large with text-medium).
+
+### Don't:
+
+- Don’t use p-heading styles for hero or marketing intros—use p-display instead.
+- Don’t mix heading sizes inconsistently within the same view.
+- Don’t center-align headings in content-heavy layouts unless intended for a special moment.
+
+## Accessibility support
+
+This component does not include any special accessibility features.
+
+## Development considerations
+
+### Heading hierarchy
+
+While using the `Heading` 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 the semantic hierarchy, not just visual size.
+- **Do** keep one unique `h1` per page.
+- **Don't** choose a heading level based on appearance alone.
+- **Don't** skip heading levels when nesting sections.
+
+## API
+
+### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `align` | `'start'` `'center'` `'end'` `'inherit'` | `'start'` | Sets the horizontal text alignment (`start`, `center`, `end`, or `inherit`). |
+| `color` | `'primary'` `'contrast-higher'` `'contrast-high'` `'contrast-medium'` `'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. Cannot be combined with multi-line content. |
+| `hyphens` | `'none'` `'manual'` `'auto'` `'inherit'` | `'none'` | Controls hyphenation behavior — `auto` lets the browser decide, `manual` only breaks at `­`, `none` disables it entirely. |
+| `size` | `'2xs'` `'xs'` `'sm'` `'md'` `'lg'` `'xl'` `'2xl'` `'3xl'` `'4xl'` `'5xl'` `'inherit'`<br>_deprecated:_ `'small'` `'medium'` `'large'` `'x-large'` `'xx-large'`<br>`BreakpointCustomizable<HeadingSize>` | `'2xl'` | Sets the visual size of the heading. Use `inherit` to derive size from the parent. 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`. |
+| `weight` | `'normal'` `'semibold'` `'bold'`<br>_deprecated:_ `'regular'` `'semi-bold'` | `'normal'` | Sets the font weight — `normal`, `semibold`, or `bold`. |
+
+### Slots
+
+| Slot | Required | Allowed tag names | Description |
+| --- | --- | --- | --- |
+| _(default)_ | no | — | Default slot to render the heading. |
+
+## Examples
+
+| Example | When to use | File |
+| --- | --- | --- |
+| Default | Minimal default configuration. | [./examples/Default.tsx](./examples/Default.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/skill/references/components/p-icon/examples/Color.tsx

@@ -0,0 +1,13 @@
+import React from 'react';
+import { PIcon, PText } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PText style={{'color': 'light-dark(mediumvioletred, deeppink)'}} color="inherit">
+        <PIcon className="me-static-sm" color="inherit" name="highway" aria={{'aria-label': 'Highway icon'}}></PIcon>
+        Some text
+      </PText>
+    </>
+  )
+}

package/skill/references/components/p-icon/examples/ColorCssVar.tsx

@@ -0,0 +1,10 @@
+import React from 'react';
+import { PIcon } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PIcon className="[--p-icon-color:deeppink]" name="highway" aria={{'aria-label': 'Highway icon'}}></PIcon>
+    </>
+  )
+}

package/skill/references/components/p-icon/examples/Custom.tsx

@@ -0,0 +1,10 @@
+import React from 'react';
+import { PIcon } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PIcon source="assets/icon-custom-kaixin.svg" aria={{'aria-label': 'Icon for social media platform Kaixin'}}></PIcon>
+    </>
+  )
+}

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

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