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

package/esm/lib/components/segmented-control.wrapper.d.ts

@@ -2,145 +2,145 @@ import type { BaseProps } from '../../BaseProps';
 import type { BreakpointCustomizable, SegmentedControlColumns, SegmentedControlChangeEventDetail, SegmentedControlState } from '../types';
 export type PSegmentedControlProps = BaseProps & {
     /**
-     * Sets the amount of columns.
+     * Sets the number of equal-width columns for the item layout. Use `auto` to distribute items based on their content width. Supports responsive breakpoint values.
      * @default 'auto'
      */
     columns?: BreakpointCustomizable<SegmentedControlColumns>;
     /**
-     * Displays the segmented control in compact mode.
+     * Reduces the item height and spacing for use in dense layouts where vertical space is limited.
      * @default false
      */
     compact?: boolean;
     /**
-     * Supplementary text providing more context or explanation for the segmented-control.
+     * Sets a supplementary description displayed below the label to give users additional context about the segmented control.
      * @default ''
      */
     description?: string;
     /**
-     * Disables the segmented-control.
+     * Prevents user interaction with all items in the segmented control and excludes the value from form submissions.
      * @default false
      */
     disabled?: boolean;
     /**
-     * The id of a form element the segmented-control should be associated with.
+     * Associates the segmented control with a form element by its ID when it is not a direct descendant of that form.
      */
     form?: string;
     /**
-     * Shows or hides the label. For better accessibility, it is recommended to show the label.
+     * Hides the visible label while keeping it accessible to screen readers. Supports responsive breakpoint values.
      * @default false
      */
     hideLabel?: BreakpointCustomizable<boolean>;
     /**
-     * Text content for a user-facing label.
+     * Sets the visible label text displayed above the segmented control to describe the group of options.
      * @default ''
      */
     label?: string;
     /**
-     * Dynamic feedback text for validation or status.
+     * Sets the validation feedback message displayed below the segmented control when `state` is `success` or `error`.
      * @default ''
      */
     message?: string;
     /**
-     * The name of the segmented-control.
+     * Sets the name of the control submitted with the form data to identify the selected value on the server.
      */
     name?: string;
     /**
-     * If true, prevents items from wrapping to new rows and renders them in a single scrollable row instead.
+     * Prevents items from wrapping to new rows and renders them in a single horizontally scrollable row instead.
      * @default false
      */
     noWrap?: boolean;
     /**
-     * Emitted when the segmented-control has lost focus.
+     * Emitted when the segmented control loses focus, useful for triggering validation on blur.
      */
     onBlur?: (event: CustomEvent<void>) => void;
     /**
-     * Emitted when the selection is changed.
+     * Emitted when the user selects a different item, carrying the new value in the event detail.
      */
     onChange?: (event: CustomEvent<SegmentedControlChangeEventDetail>) => void;
     /**
-     * A boolean value that specifies a selection must be made from the group before the form can be submitted.
+     * Marks the segmented control as required so the form cannot be submitted until one option is selected.
      * @default false
      */
     required?: boolean;
     /**
-     * Indicates the validation or overall status of the component.
+     * Sets the validation state of the segmented control, controlling its visual appearance and feedback message style (`none`, `success`, `error`).
      * @default 'none'
      */
     state?: SegmentedControlState;
     /**
-     * Sets the initial value of the segmented-control.
+     * Sets the currently selected item's value and pre-selects the matching option when the component renders.
      */
     value?: string | number;
 };
 export declare const PSegmentedControl: 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 the amount of columns.
+     * Sets the number of equal-width columns for the item layout. Use `auto` to distribute items based on their content width. Supports responsive breakpoint values.
      * @default 'auto'
      */
     columns?: BreakpointCustomizable<SegmentedControlColumns>;
     /**
-     * Displays the segmented control in compact mode.
+     * Reduces the item height and spacing for use in dense layouts where vertical space is limited.
      * @default false
      */
     compact?: boolean;
     /**
-     * Supplementary text providing more context or explanation for the segmented-control.
+     * Sets a supplementary description displayed below the label to give users additional context about the segmented control.
      * @default ''
      */
     description?: string;
     /**
-     * Disables the segmented-control.
+     * Prevents user interaction with all items in the segmented control and excludes the value from form submissions.
      * @default false
      */
     disabled?: boolean;
     /**
-     * The id of a form element the segmented-control should be associated with.
+     * Associates the segmented control with a form element by its ID when it is not a direct descendant of that form.
      */
     form?: string;
     /**
-     * Shows or hides the label. For better accessibility, it is recommended to show the label.
+     * Hides the visible label while keeping it accessible to screen readers. Supports responsive breakpoint values.
      * @default false
      */
     hideLabel?: BreakpointCustomizable<boolean>;
     /**
-     * Text content for a user-facing label.
+     * Sets the visible label text displayed above the segmented control to describe the group of options.
      * @default ''
      */
     label?: string;
     /**
-     * Dynamic feedback text for validation or status.
+     * Sets the validation feedback message displayed below the segmented control when `state` is `success` or `error`.
      * @default ''
      */
     message?: string;
     /**
-     * The name of the segmented-control.
+     * Sets the name of the control submitted with the form data to identify the selected value on the server.
      */
     name?: string;
     /**
-     * If true, prevents items from wrapping to new rows and renders them in a single scrollable row instead.
+     * Prevents items from wrapping to new rows and renders them in a single horizontally scrollable row instead.
      * @default false
      */
     noWrap?: boolean;
     /**
-     * Emitted when the segmented-control has lost focus.
+     * Emitted when the segmented control loses focus, useful for triggering validation on blur.
      */
     onBlur?: (event: CustomEvent<void>) => void;
     /**
-     * Emitted when the selection is changed.
+     * Emitted when the user selects a different item, carrying the new value in the event detail.
      */
     onChange?: (event: CustomEvent<SegmentedControlChangeEventDetail>) => void;
     /**
-     * A boolean value that specifies a selection must be made from the group before the form can be submitted.
+     * Marks the segmented control as required so the form cannot be submitted until one option is selected.
      * @default false
      */
     required?: boolean;
     /**
-     * Indicates the validation or overall status of the component.
+     * Sets the validation state of the segmented control, controlling its visual appearance and feedback message style (`none`, `success`, `error`).
      * @default 'none'
      */
     state?: SegmentedControlState;
     /**
-     * Sets the initial value of the segmented-control.
+     * Sets the currently selected item's value and pre-selects the matching option when the component renders.
      */
     value?: string | number;
 } & {

package/esm/lib/components/select-option.wrapper.d.ts

@@ -1,23 +1,23 @@
 import type { BaseProps } from '../../BaseProps';
 export type PSelectOptionProps = BaseProps & {
     /**
-     * Disables the option.
+     * Prevents the option from being selected and visually dims it to indicate it is unavailable.
      * @default false
      */
     disabled?: boolean;
     /**
-     * The option value. Selected when it strictly matches the p-select value (same type and value).
+     * Sets the value submitted with the form data when this option is selected in the parent select control.
      */
     value?: string | number | null;
 };
 export declare const PSelectOption: 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"> & {
     /**
-     * Disables the option.
+     * Prevents the option from being selected and visually dims it to indicate it is unavailable.
      * @default false
      */
     disabled?: boolean;
     /**
-     * The option value. Selected when it strictly matches the p-select value (same type and value).
+     * Sets the value submitted with the form data when this option is selected in the parent select control.
      */
     value?: string | number | null;
 } & {

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

@@ -2,72 +2,72 @@ import type { BaseProps } from '../../BaseProps';
 import type { SelectDropdownDirection, BreakpointCustomizable, SelectChangeEventDetail, SelectToggleEventDetail, SelectState } from '../types';
 export type PSelectProps = BaseProps & {
     /**
-     * Displays the select in compact mode.
+     * Reduces the control height and padding for use in dense layouts where vertical space is limited.
      * @default false
      */
     compact?: boolean;
     /**
-     * Supplementary text providing more context or explanation for the select.
+     * Sets a supplementary description displayed below the label to give users additional guidance about the select.
      * @default ''
      */
     description?: string;
     /**
-     * Disables the select.
+     * Prevents user interaction with the select and excludes its value from form submissions.
      * @default false
      */
     disabled?: boolean;
     /**
-     * Changes the direction to which the dropdown list appears.
+     * Controls whether the dropdown list opens upward (`up`) or downward (`down`), or determines the direction automatically (`auto`).
      * @default 'auto'
      */
     dropdownDirection?: SelectDropdownDirection;
     /**
-     * Shows an input in the dropdown allowing options to be filtered. Will be ignored if the `filter` slot is used.
+     * Shows a text input inside the dropdown that filters the visible options as the user types. Ignored when the `filter` slot is used.
      * @default false
      */
     filter?: boolean;
     /**
-     * The id of a form element the select should be associated with.
+     * Associates the select with a form element by its ID when it is not a direct descendant of that form.
      */
     form?: string;
     /**
-     * Shows or hides the label. For better accessibility, it is recommended to show the label.
+     * Hides the visible label while keeping it accessible to screen readers. Supports responsive breakpoint values.
      * @default false
      */
     hideLabel?: BreakpointCustomizable<boolean>;
     /**
-     * Text content for a user-facing label.
+     * Sets the visible label text displayed above the select control to identify its purpose.
      * @default ''
      */
     label?: string;
     /**
-     * The message styled depending on validation state.
+     * Sets the validation feedback message displayed below the select when `state` is `success` or `error`.
      * @default ''
      */
     message?: string;
     /**
-     * The name of the control.
+     * Sets the name of the control submitted with the form data, identifying the selected value on the server.
      */
     name: string;
     /**
-     * Emitted when the select has lost focus.
+     * Emitted when the select component loses focus, useful for triggering validation on blur.
      */
     onBlur?: (event: CustomEvent<void>) => void;
     /**
-     * Emitted when the selection is changed.
+     * Emitted when the user selects a different option, carrying the new value in the event detail.
      */
     onChange?: (event: CustomEvent<SelectChangeEventDetail>) => void;
     /**
-     * Emitted when the dropdown is toggled.
+     * Emitted when the dropdown list opens or closes, carrying the new `isOpen` state in the event detail.
      */
     onToggle?: (event: CustomEvent<SelectToggleEventDetail>) => void;
     /**
-     * Requires an option with a non-empty string value to be selected.
+     * Marks the select as required so the form cannot be submitted unless a non-empty option is selected.
      * @default false
      */
     required?: boolean;
     /**
-     * The validation state.
+     * Sets the validation state of the select, which controls its visual appearance and feedback message style (`none`, `success`, `error`).
      * @default 'none'
      */
     state?: SelectState;
@@ -78,72 +78,72 @@ export type PSelectProps = BaseProps & {
 };
 export declare const PSelect: 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 select in compact mode.
+     * Reduces the control height and padding for use in dense layouts where vertical space is limited.
      * @default false
      */
     compact?: boolean;
     /**
-     * Supplementary text providing more context or explanation for the select.
+     * Sets a supplementary description displayed below the label to give users additional guidance about the select.
      * @default ''
      */
     description?: string;
     /**
-     * Disables the select.
+     * Prevents user interaction with the select and excludes its value from form submissions.
      * @default false
      */
     disabled?: boolean;
     /**
-     * Changes the direction to which the dropdown list appears.
+     * Controls whether the dropdown list opens upward (`up`) or downward (`down`), or determines the direction automatically (`auto`).
      * @default 'auto'
      */
     dropdownDirection?: SelectDropdownDirection;
     /**
-     * Shows an input in the dropdown allowing options to be filtered. Will be ignored if the `filter` slot is used.
+     * Shows a text input inside the dropdown that filters the visible options as the user types. Ignored when the `filter` slot is used.
      * @default false
      */
     filter?: boolean;
     /**
-     * The id of a form element the select should be associated with.
+     * Associates the select with a form element by its ID when it is not a direct descendant of that form.
      */
     form?: string;
     /**
-     * Shows or hides the label. For better accessibility, it is recommended to show the label.
+     * Hides the visible label while keeping it accessible to screen readers. Supports responsive breakpoint values.
      * @default false
      */
     hideLabel?: BreakpointCustomizable<boolean>;
     /**
-     * Text content for a user-facing label.
+     * Sets the visible label text displayed above the select control to identify its purpose.
      * @default ''
      */
     label?: string;
     /**
-     * The message styled depending on validation state.
+     * Sets the validation feedback message displayed below the select when `state` is `success` or `error`.
      * @default ''
      */
     message?: string;
     /**
-     * The name of the control.
+     * Sets the name of the control submitted with the form data, identifying the selected value on the server.
      */
     name: string;
     /**
-     * Emitted when the select has lost focus.
+     * Emitted when the select component loses focus, useful for triggering validation on blur.
      */
     onBlur?: (event: CustomEvent<void>) => void;
     /**
-     * Emitted when the selection is changed.
+     * Emitted when the user selects a different option, carrying the new value in the event detail.
      */
     onChange?: (event: CustomEvent<SelectChangeEventDetail>) => void;
     /**
-     * Emitted when the dropdown is toggled.
+     * Emitted when the dropdown list opens or closes, carrying the new `isOpen` state in the event detail.
      */
     onToggle?: (event: CustomEvent<SelectToggleEventDetail>) => void;
     /**
-     * Requires an option with a non-empty string value to be selected.
+     * Marks the select as required so the form cannot be submitted unless a non-empty option is selected.
      * @default false
      */
     required?: boolean;
     /**
-     * The validation state.
+     * Sets the validation state of the select, which controls its visual appearance and feedback message style (`none`, `success`, `error`).
      * @default 'none'
      */
     state?: SelectState;

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

@@ -2,76 +2,76 @@ import type { BaseProps } from '../../BaseProps';
 import type { SelectedAriaAttributes, SheetAriaAttribute, SheetBackground, SheetMotionHiddenEndEventDetail, SheetMotionVisibleEndEventDetail } from '../types';
 export type PSheetProps = BaseProps & {
     /**
-     * Sets ARIA attributes.
+     * Sets ARIA attributes on the sheet dialog element for improved accessibility when the default `aria-label` is insufficient.
      */
     aria?: SelectedAriaAttributes<SheetAriaAttribute>;
     /**
-     * Defines the background color
+     * Sets the background color of the sheet panel (`canvas` or `surface`).
      * @default 'canvas'
      */
     background?: SheetBackground;
     /**
-     * If true, the sheet will not be closable via backdrop click.
+     * When enabled, clicking the backdrop will not close the sheet.
      * @default false
      */
     disableBackdropClick?: boolean;
     /**
-     * If false, the sheet will not have a dismiss button.
+     * Shows a dismiss button in the sheet header so users can manually close it.
      * @default true
      */
     dismissButton?: boolean;
     /**
-     * Emitted when the component requests to be dismissed.
+     * Emitted when the user dismisses the sheet via the close button, backdrop click, or Escape key.
      */
     onDismiss?: (event: CustomEvent<void>) => void;
     /**
-     * Emitted when the sheet is closed and the transition is finished.
+     * Emitted after the sheet's close transition has fully completed and the panel is hidden.
      */
     onMotionHiddenEnd?: (event: CustomEvent<SheetMotionHiddenEndEventDetail>) => void;
     /**
-     * Emitted when the sheet is opened and the transition is finished.
+     * Emitted after the sheet's open transition has fully completed and the panel is visible.
      */
     onMotionVisibleEnd?: (event: CustomEvent<SheetMotionVisibleEndEventDetail>) => void;
     /**
-     * If true, the sheet is open.
+     * Controls whether the sheet panel slides in from the bottom and is visible to the user.
      * @default false
      */
     open: boolean;
 };
 export declare const PSheet: 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 sheet dialog element for improved accessibility when the default `aria-label` is insufficient.
      */
     aria?: SelectedAriaAttributes<SheetAriaAttribute>;
     /**
-     * Defines the background color
+     * Sets the background color of the sheet panel (`canvas` or `surface`).
      * @default 'canvas'
      */
     background?: SheetBackground;
     /**
-     * If true, the sheet will not be closable via backdrop click.
+     * When enabled, clicking the backdrop will not close the sheet.
      * @default false
      */
     disableBackdropClick?: boolean;
     /**
-     * If false, the sheet will not have a dismiss button.
+     * Shows a dismiss button in the sheet header so users can manually close it.
      * @default true
      */
     dismissButton?: boolean;
     /**
-     * Emitted when the component requests to be dismissed.
+     * Emitted when the user dismisses the sheet via the close button, backdrop click, or Escape key.
      */
     onDismiss?: (event: CustomEvent<void>) => void;
     /**
-     * Emitted when the sheet is closed and the transition is finished.
+     * Emitted after the sheet's close transition has fully completed and the panel is hidden.
      */
     onMotionHiddenEnd?: (event: CustomEvent<SheetMotionHiddenEndEventDetail>) => void;
     /**
-     * Emitted when the sheet is opened and the transition is finished.
+     * Emitted after the sheet's open transition has fully completed and the panel is visible.
      */
     onMotionVisibleEnd?: (event: CustomEvent<SheetMotionVisibleEndEventDetail>) => void;
     /**
-     * If true, the sheet is open.
+     * Controls whether the sheet panel slides in from the bottom and is visible to the user.
      * @default false
      */
     open: boolean;

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

@@ -2,32 +2,32 @@ import type { BaseProps } from '../../BaseProps';
 import type { SelectedAriaAttributes, SpinnerAriaAttribute, SpinnerColor, BreakpointCustomizable, SpinnerSize } from '../types';
 export type PSpinnerProps = BaseProps & {
     /**
-     * Sets ARIA attributes.
+     * Sets ARIA attributes on the spinner's live region element; use `aria-label` to provide a descriptive loading message for screen readers.
      */
     aria?: SelectedAriaAttributes<SpinnerAriaAttribute>;
     /**
-     * Basic color variations.
+     * Sets the color of the spinning indicator using PDS semantic color tokens (e.g. `primary`, `contrast-high`, `inherit`).
      * @default 'primary'
      */
     color?: SpinnerColor;
     /**
-     * Defines the size of the spinner, aligned with the typographic scale used by components such as p-icon, p-flag, p-text, and p-heading. When set to `inherit`, the size is derived from a custom font-size defined on a parent element, calculated against the global line-height (based on `ex`-unit) to remain visually consistent with other typographic-scale-based components.
+     * Sets the size of the spinner using the PDS typographic scale. Use `inherit` to derive the size from the parent element's font-size. Supports responsive breakpoint values.
      * @default 'sm'
      */
     size?: BreakpointCustomizable<SpinnerSize>;
 };
 export declare const PSpinner: 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 spinner's live region element; use `aria-label` to provide a descriptive loading message for screen readers.
      */
     aria?: SelectedAriaAttributes<SpinnerAriaAttribute>;
     /**
-     * Basic color variations.
+     * Sets the color of the spinning indicator using PDS semantic color tokens (e.g. `primary`, `contrast-high`, `inherit`).
      * @default 'primary'
      */
     color?: SpinnerColor;
     /**
-     * Defines the size of the spinner, aligned with the typographic scale used by components such as p-icon, p-flag, p-text, and p-heading. When set to `inherit`, the size is derived from a custom font-size defined on a parent element, calculated against the global line-height (based on `ex`-unit) to remain visually consistent with other typographic-scale-based components.
+     * Sets the size of the spinner using the PDS typographic scale. Use `inherit` to derive the size from the parent element's font-size. Supports responsive breakpoint values.
      * @default 'sm'
      */
     size?: BreakpointCustomizable<SpinnerSize>;

package/esm/lib/components/stepper-horizontal-item.wrapper.d.ts

@@ -7,7 +7,7 @@ export type PStepperHorizontalItemProps = BaseProps & {
      */
     disabled?: boolean;
     /**
-     * The validation state.
+     * The current progression state of the step. Use `current` for the active step, `complete` for finished steps, `warning` for steps with issues. Leave unset for future steps.
      */
     state?: StepperHorizontalItemState;
 };
@@ -18,7 +18,7 @@ export declare const PStepperHorizontalItem: import("react").ForwardRefExoticCom
      */
     disabled?: boolean;
     /**
-     * The validation state.
+     * The current progression state of the step. Use `current` for the active step, `complete` for finished steps, `warning` for steps with issues. Leave unset for future steps.
      */
     state?: StepperHorizontalItemState;
 } & {

package/esm/lib/components/stepper-horizontal.wrapper.d.ts

@@ -6,7 +6,7 @@ export type PStepperHorizontalProps = BaseProps & {
      */
     onUpdate?: (event: CustomEvent<StepperHorizontalUpdateEventDetail>) => void;
     /**
-     * The text size.
+     * The font size of the step labels.
      * @default 'small'
      */
     size?: BreakpointCustomizable<StepperHorizontalSize>;
@@ -17,7 +17,7 @@ export declare const PStepperHorizontal: import("react").ForwardRefExoticCompone
      */
     onUpdate?: (event: CustomEvent<StepperHorizontalUpdateEventDetail>) => void;
     /**
-     * The text size.
+     * The font size of the step labels.
      * @default 'small'
      */
     size?: BreakpointCustomizable<StepperHorizontalSize>;