@porsche-design-system/components-react 4.2.0-rc.4 → 4.2.0

package/esm/lib/components/display.wrapper.d.ts

@@ -2,54 +2,54 @@ import type { BaseProps } from '../../BaseProps';
 import type { DisplayAlign, DisplayColor, BreakpointCustomizable, DisplaySize, DisplayTag } from '../types';
 export type PDisplayProps = BaseProps & {
     /**
-     * Text alignment of the component.
+     * Sets the horizontal text alignment (`start`, `center`, `end`, or `inherit`).
      * @default 'start'
      */
     align?: DisplayAlign;
     /**
-     * Basic text color variations.
+     * Sets the text color using PDS color tokens.
      * @default 'primary'
      */
     color?: DisplayColor;
     /**
-     * Adds an ellipsis to a single line of text if it overflows.
+     * Truncates the text with an ellipsis when it overflows the container on a single line.
      * @default false
      */
     ellipsis?: boolean;
     /**
-     * Size of the component. Also defines the size for specific breakpoints, like {base: "medium", l: "large"}. You always need to provide a base value when doing this.
+     * Sets the visual text size. Supports responsive breakpoint values.
      * @default 'large'
      */
     size?: BreakpointCustomizable<DisplaySize>;
     /**
-     * Sets a heading tag, so it fits correctly within the outline of the page.
+     * Sets the HTML heading tag (h1–h6) for correct document outline placement. When omitted, the tag is inferred from `size`.
      */
     tag?: DisplayTag;
 };
 /** @deprecated since v4.0.0, will be removed with next major release. Please use `p-heading` instead. */
 export declare const PDisplay: import("react").ForwardRefExoticComponent<Omit<import("react").DOMAttributes<{}>, "onChange" | "onInput" | "onToggle"> & Pick<import("react").HTMLAttributes<{}>, "suppressHydrationWarning" | "autoFocus" | "className" | "dir" | "hidden" | "id" | "inert" | "inputMode" | "lang" | "slot" | "style" | "tabIndex" | "title" | "translate" | "role"> & {
     /**
-     * Text alignment of the component.
+     * Sets the horizontal text alignment (`start`, `center`, `end`, or `inherit`).
      * @default 'start'
      */
     align?: DisplayAlign;
     /**
-     * Basic text color variations.
+     * Sets the text color using PDS color tokens.
      * @default 'primary'
      */
     color?: DisplayColor;
     /**
-     * Adds an ellipsis to a single line of text if it overflows.
+     * Truncates the text with an ellipsis when it overflows the container on a single line.
      * @default false
      */
     ellipsis?: boolean;
     /**
-     * Size of the component. Also defines the size for specific breakpoints, like {base: "medium", l: "large"}. You always need to provide a base value when doing this.
+     * Sets the visual text size. Supports responsive breakpoint values.
      * @default 'large'
      */
     size?: BreakpointCustomizable<DisplaySize>;
     /**
-     * Sets a heading tag, so it fits correctly within the outline of the page.
+     * Sets the HTML heading tag (h1–h6) for correct document outline placement. When omitted, the tag is inferred from `size`.
      */
     tag?: DisplayTag;
 } & {

package/esm/lib/components/divider.wrapper.d.ts

@@ -2,24 +2,24 @@ import type { BaseProps } from '../../BaseProps';
 import type { DividerColor, BreakpointCustomizable, DividerDirection } from '../types';
 export type PDividerProps = BaseProps & {
     /**
-     * Defines color.
+     * Sets the color of the divider line using PDS contrast tokens.
      * @default 'contrast-lower'
      */
     color?: DividerColor;
     /**
-     * Defines direction.
+     * Sets the orientation of the divider to `horizontal` or `vertical`. Supports responsive breakpoint values.
      * @default 'horizontal'
      */
     direction?: BreakpointCustomizable<DividerDirection>;
 };
 export declare const PDivider: import("react").ForwardRefExoticComponent<Omit<import("react").DOMAttributes<{}>, "onChange" | "onInput" | "onToggle"> & Pick<import("react").HTMLAttributes<{}>, "suppressHydrationWarning" | "autoFocus" | "className" | "dir" | "hidden" | "id" | "inert" | "inputMode" | "lang" | "slot" | "style" | "tabIndex" | "title" | "translate" | "role"> & {
     /**
-     * Defines color.
+     * Sets the color of the divider line using PDS contrast tokens.
      * @default 'contrast-lower'
      */
     color?: DividerColor;
     /**
-     * Defines direction.
+     * Sets the orientation of the divider to `horizontal` or `vertical`. Supports responsive breakpoint values.
      * @default 'horizontal'
      */
     direction?: BreakpointCustomizable<DividerDirection>;

package/esm/lib/components/drilldown-item.wrapper.d.ts

@@ -6,11 +6,11 @@ export type PDrilldownItemProps = BaseProps & {
      */
     cascade?: boolean;
     /**
-     * Unique identifier which controls if this item should be shown when the active-identifier on the drilldown is set to this value.
+     * Sets the unique identifier matched against the drilldown's `activeIdentifier` to determine if this item is shown.
      */
     identifier: string;
     /**
-     * Renders back button, header section on mobile view and cascade button to reach a deeper level of the navigation structure.
+     * Sets the text used for the back button, sticky header, and cascade button that navigates into this navigation level.
      */
     label?: string;
     /**
@@ -31,11 +31,11 @@ export declare const PDrilldownItem: import("react").ForwardRefExoticComponent<O
      */
     cascade?: boolean;
     /**
-     * Unique identifier which controls if this item should be shown when the active-identifier on the drilldown is set to this value.
+     * Sets the unique identifier matched against the drilldown's `activeIdentifier` to determine if this item is shown.
      */
     identifier: string;
     /**
-     * Renders back button, header section on mobile view and cascade button to reach a deeper level of the navigation structure.
+     * Sets the text used for the back button, sticky header, and cascade button that navigates into this navigation level.
      */
     label?: string;
     /**

package/esm/lib/components/drilldown-link.wrapper.d.ts

@@ -2,56 +2,56 @@ import type { BaseProps } from '../../BaseProps';
 import type { SelectedAriaAttributes, DrilldownLinkAriaAttribute, DrilldownLinkTarget } from '../types';
 export type PDrilldownLinkProps = BaseProps & {
     /**
-     * Displays the link in its active state.
+     * Visually marks the link as the currently active navigation item, e.g. the current page.
      * @default false
      */
     active?: boolean;
     /**
-     * Add ARIA attributes (only has effect when `href` is defined and no slotted anchor is used).
+     * Sets ARIA attributes on the link for improved accessibility. Only applies when `href` is set.
      */
     aria?: SelectedAriaAttributes<DrilldownLinkAriaAttribute>;
     /**
-     * Sets the native `download` attribute when the target URL points to a downloadable file (only has effect when `href` is defined and no slotted anchor is used).
+     * Sets the native `download` attribute to trigger a file download. Only applies when `href` is set.
      */
     download?: string;
     /**
-     * When `href` is provided, the component renders as an `<a>` element. Otherwise, provide a slotted anchor element.
+     * When set, the component renders as an anchor navigating to this URL. Otherwise, provide a slotted anchor element.
      */
     href?: string;
     /**
-     * Sets the `rel` attribute on the link (only has effect when `href` is defined and no slotted anchor is used).
+     * Sets the `rel` attribute on the link element (e.g. `noopener`). Only applies when `href` is set.
      */
     rel?: string;
     /**
-     * Target attribute where the link should be opened (only has effect when `href` is defined and no slotted anchor is used).
+     * Specifies where to open the linked URL (e.g. `_self`, `_blank`). Only applies when `href` is set.
      * @default '_self'
      */
     target?: DrilldownLinkTarget;
 };
 export declare const PDrilldownLink: import("react").ForwardRefExoticComponent<Omit<import("react").DOMAttributes<{}>, "onChange" | "onInput" | "onToggle"> & Pick<import("react").HTMLAttributes<{}>, "suppressHydrationWarning" | "autoFocus" | "className" | "dir" | "hidden" | "id" | "inert" | "inputMode" | "lang" | "slot" | "style" | "tabIndex" | "title" | "translate" | "role"> & {
     /**
-     * Displays the link in its active state.
+     * Visually marks the link as the currently active navigation item, e.g. the current page.
      * @default false
      */
     active?: boolean;
     /**
-     * Add ARIA attributes (only has effect when `href` is defined and no slotted anchor is used).
+     * Sets ARIA attributes on the link for improved accessibility. Only applies when `href` is set.
      */
     aria?: SelectedAriaAttributes<DrilldownLinkAriaAttribute>;
     /**
-     * Sets the native `download` attribute when the target URL points to a downloadable file (only has effect when `href` is defined and no slotted anchor is used).
+     * Sets the native `download` attribute to trigger a file download. Only applies when `href` is set.
      */
     download?: string;
     /**
-     * When `href` is provided, the component renders as an `<a>` element. Otherwise, provide a slotted anchor element.
+     * When set, the component renders as an anchor navigating to this URL. Otherwise, provide a slotted anchor element.
      */
     href?: string;
     /**
-     * Sets the `rel` attribute on the link (only has effect when `href` is defined and no slotted anchor is used).
+     * Sets the `rel` attribute on the link element (e.g. `noopener`). Only applies when `href` is set.
      */
     rel?: string;
     /**
-     * Target attribute where the link should be opened (only has effect when `href` is defined and no slotted anchor is used).
+     * Specifies where to open the linked URL (e.g. `_self`, `_blank`). Only applies when `href` is set.
      * @default '_self'
      */
     target?: DrilldownLinkTarget;

package/esm/lib/components/drilldown.wrapper.d.ts

@@ -2,46 +2,46 @@ import type { BaseProps } from '../../BaseProps';
 import type { SelectedAriaAttributes, DrilldownAriaAttribute, DrilldownUpdateEventDetail } from '../types';
 export type PDrilldownProps = BaseProps & {
     /**
-     * Defines which `p-drilldown-item` is shown as open.
+     * Sets which `p-drilldown-item` (by `identifier`) is currently expanded to show its sub-navigation level.
      */
     activeIdentifier?: string | undefined;
     /**
-     * Sets ARIA attributes.
+     * Sets ARIA attributes on the drilldown dialog element for improved screen reader accessibility.
      */
     aria?: SelectedAriaAttributes<DrilldownAriaAttribute>;
     /**
-     * Emitted when the component requests to be dismissed.
+     * Emitted when the user closes the drilldown via the close button or Escape key.
      */
     onDismiss?: (event: CustomEvent<void>) => void;
     /**
-     * Emitted when `activeIdentifier` changes.
+     * Emitted when the active navigation level changes, with the new `activeIdentifier` in the event detail.
      */
     onUpdate?: (event: CustomEvent<DrilldownUpdateEventDetail>) => void;
     /**
-     * If `true`, the drilldown is shown as open.
+     * Controls whether the drilldown navigation panel is visible.
      * @default false
      */
     open?: boolean;
 };
 export declare const PDrilldown: import("react").ForwardRefExoticComponent<Omit<import("react").DOMAttributes<{}>, "onChange" | "onInput" | "onToggle"> & Pick<import("react").HTMLAttributes<{}>, "suppressHydrationWarning" | "autoFocus" | "className" | "dir" | "hidden" | "id" | "inert" | "inputMode" | "lang" | "slot" | "style" | "tabIndex" | "title" | "translate" | "role"> & {
     /**
-     * Defines which `p-drilldown-item` is shown as open.
+     * Sets which `p-drilldown-item` (by `identifier`) is currently expanded to show its sub-navigation level.
      */
     activeIdentifier?: string | undefined;
     /**
-     * Sets ARIA attributes.
+     * Sets ARIA attributes on the drilldown dialog element for improved screen reader accessibility.
      */
     aria?: SelectedAriaAttributes<DrilldownAriaAttribute>;
     /**
-     * Emitted when the component requests to be dismissed.
+     * Emitted when the user closes the drilldown via the close button or Escape key.
      */
     onDismiss?: (event: CustomEvent<void>) => void;
     /**
-     * Emitted when `activeIdentifier` changes.
+     * Emitted when the active navigation level changes, with the new `activeIdentifier` in the event detail.
      */
     onUpdate?: (event: CustomEvent<DrilldownUpdateEventDetail>) => void;
     /**
-     * If `true`, the drilldown is shown as open.
+     * Controls whether the drilldown navigation panel is visible.
      * @default false
      */
     open?: boolean;

package/esm/lib/components/fieldset.wrapper.d.ts

@@ -2,62 +2,62 @@ import type { BaseProps } from '../../BaseProps';
 import type { SelectedAriaRole, FieldsetLabelSize, FieldsetState } from '../types';
 export type PFieldsetProps = BaseProps & {
     /**
-     * Sets ARIA attributes.
+     * Overrides the ARIA role on the fieldset — use `radiogroup` when grouping radio buttons.
      */
     aria?: SelectedAriaRole<"radiogroup">;
     /**
-     * Text content for a user-facing label.
+     * Sets the visible legend text displayed above the grouped form controls.
      * @default ''
      */
     label?: string;
     /**
-     * Controls the size of the label text.
+     * Sets the font size of the fieldset label (`small`, `medium`, or `large`).
      * @default 'medium'
      */
     labelSize?: FieldsetLabelSize;
     /**
-     * The message styled depending on validation state.
+     * Sets the validation feedback message displayed below the fieldset when `state` is `success` or `error`.
      * @default ''
      */
     message?: string;
     /**
-     * Marks the Fieldset as required.
+     * Marks all controls within the fieldset as required and adds a required indicator to the label.
      * @default false
      */
     required?: boolean;
     /**
-     * The validation state.
+     * Sets the validation state of the fieldset, controlling the color and style of the feedback message.
      * @default 'none'
      */
     state?: FieldsetState;
 };
 export declare const PFieldset: import("react").ForwardRefExoticComponent<Omit<import("react").DOMAttributes<{}>, "onChange" | "onInput" | "onToggle"> & Pick<import("react").HTMLAttributes<{}>, "suppressHydrationWarning" | "autoFocus" | "className" | "dir" | "hidden" | "id" | "inert" | "inputMode" | "lang" | "slot" | "style" | "tabIndex" | "title" | "translate" | "role"> & {
     /**
-     * Sets ARIA attributes.
+     * Overrides the ARIA role on the fieldset — use `radiogroup` when grouping radio buttons.
      */
     aria?: SelectedAriaRole<"radiogroup">;
     /**
-     * Text content for a user-facing label.
+     * Sets the visible legend text displayed above the grouped form controls.
      * @default ''
      */
     label?: string;
     /**
-     * Controls the size of the label text.
+     * Sets the font size of the fieldset label (`small`, `medium`, or `large`).
      * @default 'medium'
      */
     labelSize?: FieldsetLabelSize;
     /**
-     * The message styled depending on validation state.
+     * Sets the validation feedback message displayed below the fieldset when `state` is `success` or `error`.
      * @default ''
      */
     message?: string;
     /**
-     * Marks the Fieldset as required.
+     * Marks all controls within the fieldset as required and adds a required indicator to the label.
      * @default false
      */
     required?: boolean;
     /**
-     * The validation state.
+     * Sets the validation state of the fieldset, controlling the color and style of the feedback message.
      * @default 'none'
      */
     state?: FieldsetState;

package/esm/lib/components/flyout.wrapper.d.ts

@@ -1,97 +1,107 @@
 import type { BaseProps } from '../../BaseProps';
-import type { SelectedAriaAttributes, FlyoutAriaAttribute, FlyoutBackdrop, FlyoutBackground, FlyoutFooterBehavior, FlyoutMotionHiddenEndEventDetail, FlyoutMotionVisibleEndEventDetail, FlyoutPosition } from '../types';
+import type { SelectedAriaAttributes, FlyoutAriaAttribute, FlyoutBackdrop, FlyoutBackground, FlyoutFooterBehavior, BreakpointCustomizable, FlyoutMotionHiddenEndEventDetail, FlyoutMotionVisibleEndEventDetail, FlyoutPosition } from '../types';
 export type PFlyoutProps = BaseProps & {
     /**
-     * Sets ARIA attributes.
+     * Sets ARIA attributes on the flyout dialog element for improved screen reader accessibility.
      */
     aria?: SelectedAriaAttributes<FlyoutAriaAttribute>;
     /**
-     * Defines the backdrop, 'blur' (should be used when the underlying content is not relevant for users) and 'shading' (should be used when the user still needs a visual connection to the underlying content).
+     * Sets the backdrop style. Use `blur` when background content is irrelevant; use `shading` when users still need visual context.
      * @default 'blur'
      */
     backdrop?: FlyoutBackdrop;
     /**
-     * Defines the background color
+     * Sets the background color of the flyout panel (`canvas` or `surface`).
      * @default 'canvas'
      */
     background?: FlyoutBackground;
     /**
-     * If true, the flyout will not be closable via backdrop click.
+     * When enabled, clicking the backdrop will not close the flyout.
      * @default false
      */
     disableBackdropClick?: boolean;
     /**
-     * Determines the footer's position behavior. When set to "fixed," the flyout content stretches to fill the full height, keeping the footer permanently at the bottom. When set to "sticky," the footer flows beneath the content and only becomes fixed if the content overflows.
+     * Controls footer behavior. `fixed` keeps it anchored at the bottom; `sticky` pins it only when content overflows.
      * @default 'sticky'
      */
     footerBehavior?: FlyoutFooterBehavior;
     /**
-     * Emitted when the component requests to be dismissed.
+     * 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.
+     * @default false
+     */
+    fullscreen?: BreakpointCustomizable<boolean>;
+    /**
+     * Emitted when the user closes the flyout via the close button, backdrop click, or Escape key.
      */
     onDismiss?: (event: CustomEvent<void>) => void;
     /**
-     * Emitted when the flyout is closed and the transition is finished.
+     * Emitted after the flyout's close transition completes and the panel is fully hidden.
      */
     onMotionHiddenEnd?: (event: CustomEvent<FlyoutMotionHiddenEndEventDetail>) => void;
     /**
-     * Emitted when the flyout is opened and the transition is finished.
+     * Emitted after the flyout's open transition completes and the panel is fully visible.
      */
     onMotionVisibleEnd?: (event: CustomEvent<FlyoutMotionVisibleEndEventDetail>) => void;
     /**
-     * If true, the flyout is open.
+     * Controls whether the flyout panel is visible.
      * @default false
      */
     open: boolean;
     /**
-     * The position of the flyout
+     * Sets the side the flyout slides in from — `start` for left or `end` for right in LTR layouts.
      * @default 'end'
      */
     position?: FlyoutPosition;
 };
 export declare const PFlyout: import("react").ForwardRefExoticComponent<Omit<import("react").DOMAttributes<{}>, "onChange" | "onInput" | "onToggle"> & Pick<import("react").HTMLAttributes<{}>, "suppressHydrationWarning" | "autoFocus" | "className" | "dir" | "hidden" | "id" | "inert" | "inputMode" | "lang" | "slot" | "style" | "tabIndex" | "title" | "translate" | "role"> & {
     /**
-     * Sets ARIA attributes.
+     * Sets ARIA attributes on the flyout dialog element for improved screen reader accessibility.
      */
     aria?: SelectedAriaAttributes<FlyoutAriaAttribute>;
     /**
-     * Defines the backdrop, 'blur' (should be used when the underlying content is not relevant for users) and 'shading' (should be used when the user still needs a visual connection to the underlying content).
+     * Sets the backdrop style. Use `blur` when background content is irrelevant; use `shading` when users still need visual context.
      * @default 'blur'
      */
     backdrop?: FlyoutBackdrop;
     /**
-     * Defines the background color
+     * Sets the background color of the flyout panel (`canvas` or `surface`).
      * @default 'canvas'
      */
     background?: FlyoutBackground;
     /**
-     * If true, the flyout will not be closable via backdrop click.
+     * When enabled, clicking the backdrop will not close the flyout.
      * @default false
      */
     disableBackdropClick?: boolean;
     /**
-     * Determines the footer's position behavior. When set to "fixed," the flyout content stretches to fill the full height, keeping the footer permanently at the bottom. When set to "sticky," the footer flows beneath the content and only becomes fixed if the content overflows.
+     * Controls footer behavior. `fixed` keeps it anchored at the bottom; `sticky` pins it only when content overflows.
      * @default 'sticky'
      */
     footerBehavior?: FlyoutFooterBehavior;
     /**
-     * Emitted when the component requests to be dismissed.
+     * 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.
+     * @default false
+     */
+    fullscreen?: BreakpointCustomizable<boolean>;
+    /**
+     * Emitted when the user closes the flyout via the close button, backdrop click, or Escape key.
      */
     onDismiss?: (event: CustomEvent<void>) => void;
     /**
-     * Emitted when the flyout is closed and the transition is finished.
+     * Emitted after the flyout's close transition completes and the panel is fully hidden.
      */
     onMotionHiddenEnd?: (event: CustomEvent<FlyoutMotionHiddenEndEventDetail>) => void;
     /**
-     * Emitted when the flyout is opened and the transition is finished.
+     * Emitted after the flyout's open transition completes and the panel is fully visible.
      */
     onMotionVisibleEnd?: (event: CustomEvent<FlyoutMotionVisibleEndEventDetail>) => void;
     /**
-     * If true, the flyout is open.
+     * Controls whether the flyout panel is visible.
      * @default false
      */
     open: boolean;
     /**
-     * The position of the flyout
+     * Sets the side the flyout slides in from — `start` for left or `end` for right in LTR layouts.
      * @default 'end'
      */
     position?: FlyoutPosition;

package/esm/lib/components/flyout.wrapper.mjs

@@ -4,16 +4,16 @@ import { forwardRef, useRef } from 'react';
 import { useEventCallback, usePrefix, useBrowserLayoutEffect, useMergedClass } from '../../hooks.mjs';
 import { syncRef } from '../../utils.mjs';
 
-const PFlyout = /*#__PURE__*/ forwardRef(({ aria, backdrop = 'blur', background = 'canvas', disableBackdropClick = false, footerBehavior = 'sticky', onDismiss, onMotionHiddenEnd, onMotionVisibleEnd, open = false, position = 'end', className, ...rest }, ref) => {
+const PFlyout = /*#__PURE__*/ forwardRef(({ aria, backdrop = 'blur', background = 'canvas', disableBackdropClick = false, footerBehavior = 'sticky', fullscreen = false, onDismiss, onMotionHiddenEnd, onMotionVisibleEnd, open = false, position = 'end', className, ...rest }, ref) => {
     const elementRef = useRef(undefined);
     useEventCallback(elementRef, 'dismiss', onDismiss);
     useEventCallback(elementRef, 'motionHiddenEnd', onMotionHiddenEnd);
     useEventCallback(elementRef, 'motionVisibleEnd', onMotionVisibleEnd);
     const WebComponentTag = usePrefix('p-flyout');
-    const propsToSync = [aria, backdrop, background, disableBackdropClick, footerBehavior, open, position];
+    const propsToSync = [aria, backdrop, background, disableBackdropClick, footerBehavior, fullscreen, open, position];
     useBrowserLayoutEffect(() => {
         const { current } = elementRef;
-        ['aria', 'backdrop', 'background', 'disableBackdropClick', 'footerBehavior', 'open', 'position'].forEach((propName, i) => (current[propName] = propsToSync[i]));
+        ['aria', 'backdrop', 'background', 'disableBackdropClick', 'footerBehavior', 'fullscreen', 'open', 'position'].forEach((propName, i) => (current[propName] = propsToSync[i]));
     }, propsToSync);
     const props = {
         ...rest,

package/esm/lib/components/heading.wrapper.d.ts

@@ -2,72 +2,72 @@ import type { BaseProps } from '../../BaseProps';
 import type { HeadingAlign, HeadingColor, HeadingHyphens, BreakpointCustomizable, HeadingSize, HeadingTag, HeadingWeight } from '../types';
 export type PHeadingProps = BaseProps & {
     /**
-     * Text alignment of the heading. Use 'start' for left-aligned text (in LTR), 'center' for centered, 'end' for right-aligned (in LTR), or 'inherit' to adopt the parent's alignment.
+     * Sets the horizontal text alignment (`start`, `center`, `end`, or `inherit`).
      * @default 'start'
      */
     align?: HeadingAlign;
     /**
-     * Text color of the heading. Use 'primary' for default, 'contrast-higher' / 'contrast-high' / 'contrast-medium' for alternative emphasis levels, or 'inherit' to adopt the parent's color.
+     * Sets the text color using PDS color tokens.
      * @default 'primary'
      */
     color?: HeadingColor;
     /**
-     * Adds an ellipsis to a single line of text if it overflows the container width. When enabled, the text is truncated to a single line with `text-overflow: ellipsis`. Cannot be combined with multi-line content.
+     * Truncates the text with an ellipsis when it overflows the container on a single line. Cannot be combined with multi-line content.
      * @default false
      */
     ellipsis?: boolean;
     /**
-     * Controls the hyphenation behavior of the heading. Use 'auto' to let the browser automatically hyphenate words at appropriate points, 'manual' to only hyphenate at manually inserted hyphenation points (e.g. `­`), 'none' to disable hyphenation entirely, or 'inherit' to adopt the parent's hyphenation setting.
+     * Controls hyphenation behavior — `auto` lets the browser decide, `manual` only breaks at `­`, `none` disables it entirely.
      * @default 'none'
      */
     hyphens?: HeadingHyphens;
     /**
-     * Size of the heading. Also defines the size for specific breakpoints, like {base: "md", l: "2xl"}. You always need to provide a base value when doing this. Use 'inherit' to adopt the parent's font size.
+     * Sets the visual size of the heading. Use `inherit` to derive size from the parent. Supports responsive breakpoint values.
      * @default '2xl'
      */
     size?: BreakpointCustomizable<HeadingSize>;
     /**
-     * Sets the HTML heading tag (h1 - h6) to ensure the correct document outline and semantic hierarchy. If not set, the tag is automatically inferred from the `size` property (e.g. '2xl' maps to 'h2', 'md' to 'h5', 'sm' to 'h6').
+     * Sets the HTML heading tag (h1–h6) for correct document outline placement. When omitted, the tag is inferred from `size`.
      */
     tag?: HeadingTag;
     /**
-     * The font weight of the heading. Use 'normal' for regular weight, 'semibold' for slightly emphasized text, or 'bold' for strong emphasis. For `size` values of 'sm' or smaller, it's recommended to use 'semibold' for better readability.
+     * Sets the font weight — `normal`, `semibold`, or `bold`.
      * @default 'normal'
      */
     weight?: HeadingWeight;
 };
 export declare const PHeading: import("react").ForwardRefExoticComponent<Omit<import("react").DOMAttributes<{}>, "onChange" | "onInput" | "onToggle"> & Pick<import("react").HTMLAttributes<{}>, "suppressHydrationWarning" | "autoFocus" | "className" | "dir" | "hidden" | "id" | "inert" | "inputMode" | "lang" | "slot" | "style" | "tabIndex" | "title" | "translate" | "role"> & {
     /**
-     * Text alignment of the heading. Use 'start' for left-aligned text (in LTR), 'center' for centered, 'end' for right-aligned (in LTR), or 'inherit' to adopt the parent's alignment.
+     * Sets the horizontal text alignment (`start`, `center`, `end`, or `inherit`).
      * @default 'start'
      */
     align?: HeadingAlign;
     /**
-     * Text color of the heading. Use 'primary' for default, 'contrast-higher' / 'contrast-high' / 'contrast-medium' for alternative emphasis levels, or 'inherit' to adopt the parent's color.
+     * Sets the text color using PDS color tokens.
      * @default 'primary'
      */
     color?: HeadingColor;
     /**
-     * Adds an ellipsis to a single line of text if it overflows the container width. When enabled, the text is truncated to a single line with `text-overflow: ellipsis`. Cannot be combined with multi-line content.
+     * Truncates the text with an ellipsis when it overflows the container on a single line. Cannot be combined with multi-line content.
      * @default false
      */
     ellipsis?: boolean;
     /**
-     * Controls the hyphenation behavior of the heading. Use 'auto' to let the browser automatically hyphenate words at appropriate points, 'manual' to only hyphenate at manually inserted hyphenation points (e.g. `&shy;`), 'none' to disable hyphenation entirely, or 'inherit' to adopt the parent's hyphenation setting.
+     * Controls hyphenation behavior — `auto` lets the browser decide, `manual` only breaks at `&shy;`, `none` disables it entirely.
      * @default 'none'
      */
     hyphens?: HeadingHyphens;
     /**
-     * Size of the heading. Also defines the size for specific breakpoints, like {base: "md", l: "2xl"}. You always need to provide a base value when doing this. Use 'inherit' to adopt the parent's font size.
+     * Sets the visual size of the heading. Use `inherit` to derive size from the parent. Supports responsive breakpoint values.
      * @default '2xl'
      */
     size?: BreakpointCustomizable<HeadingSize>;
     /**
-     * Sets the HTML heading tag (h1 - h6) to ensure the correct document outline and semantic hierarchy. If not set, the tag is automatically inferred from the `size` property (e.g. '2xl' maps to 'h2', 'md' to 'h5', 'sm' to 'h6').
+     * Sets the HTML heading tag (h1–h6) for correct document outline placement. When omitted, the tag is inferred from `size`.
      */
     tag?: HeadingTag;
     /**
-     * The font weight of the heading. Use 'normal' for regular weight, 'semibold' for slightly emphasized text, or 'bold' for strong emphasis. For `size` values of 'sm' or smaller, it's recommended to use 'semibold' for better readability.
+     * Sets the font weight — `normal`, `semibold`, or `bold`.
      * @default 'normal'
      */
     weight?: HeadingWeight;