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

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

@@ -2,96 +2,96 @@ import type { BaseProps } from '../../BaseProps';
 import type { SelectedAriaAttributes, ModalAriaAttribute, ModalBackdrop, ModalBackground, BreakpointCustomizable, ModalMotionHiddenEndEventDetail, ModalMotionVisibleEndEventDetail } from '../types';
 export type PModalProps = BaseProps & {
     /**
-     * Sets ARIA attributes.
+     * Sets ARIA attributes on the dialog element for improved accessibility when no visible heading is present.
      */
     aria?: SelectedAriaAttributes<ModalAriaAttribute>;
     /**
-     * Defines the backdrop, 'blur' (should be used when Modal is opened by user interaction, e.g. after a click on a button) and 'shading' (should be used when Modal gets opened automatically, e.g. Cookie Consent).
+     * Sets the backdrop style. Use `blur` when the modal is opened by user interaction; use `shading` when opened automatically (e.g. Cookie Consent).
      * @default 'blur'
      */
     backdrop?: ModalBackdrop;
     /**
-     * Defines the background color
+     * Sets the background color of the modal panel (`canvas` or `surface`).
      * @default 'canvas'
      */
     background?: ModalBackground;
     /**
-     * If true, the modal will not be closable via backdrop click.
+     * When enabled, clicking the backdrop will not close the modal.
      * @default false
      */
     disableBackdropClick?: boolean;
     /**
-     * If false, the modal will not have a dismiss button.
+     * Shows a dismiss button in the modal header so the user can manually close it.
      * @default true
      */
     dismissButton?: boolean;
     /**
-     * If true the modal uses max viewport height and width. Should only be used for mobile.
+     * Expands the modal to the full viewport size, intended for mobile use cases. Supports responsive breakpoint values.
      * @default false
      */
     fullscreen?: BreakpointCustomizable<boolean>;
     /**
-     * Emitted when the component requests to be dismissed.
+     * Emitted when the user closes the modal via the dismiss button, backdrop click, or Escape key.
      */
     onDismiss?: (event: CustomEvent<void>) => void;
     /**
-     * Emitted when the modal is closed and the transition is finished.
+     * Emitted after the modal's close transition completes and the dialog is fully hidden.
      */
     onMotionHiddenEnd?: (event: CustomEvent<ModalMotionHiddenEndEventDetail>) => void;
     /**
-     * Emitted when the modal is opened and the transition is finished.
+     * Emitted after the modal's open transition completes and the dialog is fully visible.
      */
     onMotionVisibleEnd?: (event: CustomEvent<ModalMotionVisibleEndEventDetail>) => void;
     /**
-     * If true, the modal is open.
+     * Controls whether the modal dialog is visible.
      * @default false
      */
     open: boolean;
 };
 export declare const PModal: 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 dialog element for improved accessibility when no visible heading is present.
      */
     aria?: SelectedAriaAttributes<ModalAriaAttribute>;
     /**
-     * Defines the backdrop, 'blur' (should be used when Modal is opened by user interaction, e.g. after a click on a button) and 'shading' (should be used when Modal gets opened automatically, e.g. Cookie Consent).
+     * Sets the backdrop style. Use `blur` when the modal is opened by user interaction; use `shading` when opened automatically (e.g. Cookie Consent).
      * @default 'blur'
      */
     backdrop?: ModalBackdrop;
     /**
-     * Defines the background color
+     * Sets the background color of the modal panel (`canvas` or `surface`).
      * @default 'canvas'
      */
     background?: ModalBackground;
     /**
-     * If true, the modal will not be closable via backdrop click.
+     * When enabled, clicking the backdrop will not close the modal.
      * @default false
      */
     disableBackdropClick?: boolean;
     /**
-     * If false, the modal will not have a dismiss button.
+     * Shows a dismiss button in the modal header so the user can manually close it.
      * @default true
      */
     dismissButton?: boolean;
     /**
-     * If true the modal uses max viewport height and width. Should only be used for mobile.
+     * Expands the modal to the full viewport size, intended for mobile use cases. Supports responsive breakpoint values.
      * @default false
      */
     fullscreen?: BreakpointCustomizable<boolean>;
     /**
-     * Emitted when the component requests to be dismissed.
+     * Emitted when the user closes the modal via the dismiss button, backdrop click, or Escape key.
      */
     onDismiss?: (event: CustomEvent<void>) => void;
     /**
-     * Emitted when the modal is closed and the transition is finished.
+     * Emitted after the modal's close transition completes and the dialog is fully hidden.
      */
     onMotionHiddenEnd?: (event: CustomEvent<ModalMotionHiddenEndEventDetail>) => void;
     /**
-     * Emitted when the modal is opened and the transition is finished.
+     * Emitted after the modal's open transition completes and the dialog is fully visible.
      */
     onMotionVisibleEnd?: (event: CustomEvent<ModalMotionVisibleEndEventDetail>) => void;
     /**
-     * If true, the modal is open.
+     * Controls whether the modal dialog is visible.
      * @default false
      */
     open: boolean;

package/esm/lib/components/model-signature.wrapper.d.ts

@@ -2,64 +2,64 @@ import type { BaseProps } from '../../BaseProps';
 import type { ModelSignatureColor, ModelSignatureFetchPriority, ModelSignatureModel, ModelSignatureSize } from '../types';
 export type PModelSignatureProps = BaseProps & {
     /**
-     * Adapts the color of the component.
+     * Sets the fill color of the signature using PDS color tokens.
      * @default 'primary'
      */
     color?: ModelSignatureColor;
     /**
-     * Sets the browser's fetch priority hint for the model signature asset.
+     * Sets the browser's fetch priority hint for the signature asset (`auto`, `high`, `low`).
      * @default 'auto'
      */
     fetchPriority?: ModelSignatureFetchPriority;
     /**
-     * Defines whether the model signature is always loaded or only loaded when it is in the viewport (this feature may not work reliably).
+     * Defers loading the signature until it enters the viewport to improve initial page performance.
      * @default false
      */
     lazy?: boolean;
     /**
-     * Adapts the model of the component.
+     * Selects the Porsche model whose typographic signature SVG is displayed.
      * @default '911'
      */
     model?: ModelSignatureModel;
     /**
-     * When set to `true`, then all model signatures are visually aligned with each other. When set to `false` the model signature comes without any safe zone.
+     * When enabled, adds invisible padding so all model signatures visually align to a consistent baseline.
      * @default true
      */
     safeZone?: boolean;
     /**
-     * Adapts the size of the component. When set to `inherit` a CSS `width` or `height` needs to be defined on the host but not both.
+     * Sets the display size of the signature using predefined PDS sizes. Use `inherit` with a CSS `width` or `height` on the host for custom sizing.
      * @default 'small'
      */
     size?: ModelSignatureSize;
 };
 export declare const PModelSignature: 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"> & {
     /**
-     * Adapts the color of the component.
+     * Sets the fill color of the signature using PDS color tokens.
      * @default 'primary'
      */
     color?: ModelSignatureColor;
     /**
-     * Sets the browser's fetch priority hint for the model signature asset.
+     * Sets the browser's fetch priority hint for the signature asset (`auto`, `high`, `low`).
      * @default 'auto'
      */
     fetchPriority?: ModelSignatureFetchPriority;
     /**
-     * Defines whether the model signature is always loaded or only loaded when it is in the viewport (this feature may not work reliably).
+     * Defers loading the signature until it enters the viewport to improve initial page performance.
      * @default false
      */
     lazy?: boolean;
     /**
-     * Adapts the model of the component.
+     * Selects the Porsche model whose typographic signature SVG is displayed.
      * @default '911'
      */
     model?: ModelSignatureModel;
     /**
-     * When set to `true`, then all model signatures are visually aligned with each other. When set to `false` the model signature comes without any safe zone.
+     * When enabled, adds invisible padding so all model signatures visually align to a consistent baseline.
      * @default true
      */
     safeZone?: boolean;
     /**
-     * Adapts the size of the component. When set to `inherit` a CSS `width` or `height` needs to be defined on the host but not both.
+     * Sets the display size of the signature using predefined PDS sizes. Use `inherit` with a CSS `width` or `height` on the host for custom sizing.
      * @default 'small'
      */
     size?: ModelSignatureSize;

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

@@ -1,23 +1,23 @@
 import type { BaseProps } from '../../BaseProps';
 export type PMultiSelectOptionProps = BaseProps & {
     /**
-     * Disables the option.
+     * Disables the option, preventing it from being selected.
      * @default false
      */
     disabled?: boolean;
     /**
-     * The option value.
+     * Sets the value submitted with the form data when this option is selected in the parent multi-select.
      */
     value: string | number;
 };
 export declare const PMultiSelectOption: 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.
+     * Disables the option, preventing it from being selected.
      * @default false
      */
     disabled?: boolean;
     /**
-     * The option value.
+     * Sets the value submitted with the form data when this option is selected in the parent multi-select.
      */
     value: string | number;
 } & {

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

@@ -2,67 +2,67 @@ import type { BaseProps } from '../../BaseProps';
 import type { MultiSelectDropdownDirection, BreakpointCustomizable, MultiSelectChangeEventDetail, MultiSelectToggleEventDetail, MultiSelectState } from '../types';
 export type PMultiSelectProps = BaseProps & {
     /**
-     * Displays the multi-select in compact mode.
+     * Reduces the control height and padding for a more compact layout.
      * @default false
      */
     compact?: boolean;
     /**
-     * Supplementary text providing more context or explanation for the multi-select.
+     * Sets a supplementary description displayed below the label to provide additional context.
      * @default ''
      */
     description?: string;
     /**
-     * Disables the multi-select
+     * Disables the multi-select, preventing all interaction. Selected values are not submitted with the form.
      * @default false
      */
     disabled?: boolean;
     /**
-     * Changes the direction to which the dropdown list appears.
+     * Controls whether the dropdown opens upward (`up`) or downward (`down`), or decides automatically (`auto`).
      * @default 'auto'
      */
     dropdownDirection?: MultiSelectDropdownDirection;
     /**
-     * The id of a form element the multi-select should be associated with.
+     * Associates the multi-select with a form element by its ID when not directly nested inside it.
      */
     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 multi-select control.
      * @default ''
      */
     label?: string;
     /**
-     * The message styled depending on validation state.
+     * Sets the validation feedback message displayed below the control when `state` is `success` or `error`.
      * @default ''
      */
     message?: string;
     /**
-     * The name of the control.
+     * Sets the name submitted with the form data to identify the selected values on the server.
      */
     name: string;
     /**
-     * Emitted when the multi-select has lost focus.
+     * Emitted when the multi-select loses focus.
      */
     onBlur?: (event: CustomEvent<void>) => void;
     /**
-     * Emitted when the selection is changed.
+     * Emitted when the user selects or deselects an option, with the updated array of values in the event detail.
      */
     onChange?: (event: CustomEvent<MultiSelectChangeEventDetail>) => void;
     /**
-     * Emitted when the dropdown is toggled.
+     * Emitted when the dropdown opens or closes, with the new open state in the event detail.
      */
     onToggle?: (event: CustomEvent<MultiSelectToggleEventDetail>) => void;
     /**
-     * Requires an option with a non-empty string value to be selected.
+     * Marks the multi-select as required — form submission is blocked unless at least one option is selected.
      * @default false
      */
     required?: boolean;
     /**
-     * The validation state.
+     * Sets the validation state, controlling the visual appearance and style of the feedback message (`none`, `success`, `error`).
      * @default 'none'
      */
     state?: MultiSelectState;
@@ -74,67 +74,67 @@ export type PMultiSelectProps = BaseProps & {
 };
 export declare const PMultiSelect: 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 multi-select in compact mode.
+     * Reduces the control height and padding for a more compact layout.
      * @default false
      */
     compact?: boolean;
     /**
-     * Supplementary text providing more context or explanation for the multi-select.
+     * Sets a supplementary description displayed below the label to provide additional context.
      * @default ''
      */
     description?: string;
     /**
-     * Disables the multi-select
+     * Disables the multi-select, preventing all interaction. Selected values are not submitted with the form.
      * @default false
      */
     disabled?: boolean;
     /**
-     * Changes the direction to which the dropdown list appears.
+     * Controls whether the dropdown opens upward (`up`) or downward (`down`), or decides automatically (`auto`).
      * @default 'auto'
      */
     dropdownDirection?: MultiSelectDropdownDirection;
     /**
-     * The id of a form element the multi-select should be associated with.
+     * Associates the multi-select with a form element by its ID when not directly nested inside it.
      */
     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 multi-select control.
      * @default ''
      */
     label?: string;
     /**
-     * The message styled depending on validation state.
+     * Sets the validation feedback message displayed below the control when `state` is `success` or `error`.
      * @default ''
      */
     message?: string;
     /**
-     * The name of the control.
+     * Sets the name submitted with the form data to identify the selected values on the server.
      */
     name: string;
     /**
-     * Emitted when the multi-select has lost focus.
+     * Emitted when the multi-select loses focus.
      */
     onBlur?: (event: CustomEvent<void>) => void;
     /**
-     * Emitted when the selection is changed.
+     * Emitted when the user selects or deselects an option, with the updated array of values in the event detail.
      */
     onChange?: (event: CustomEvent<MultiSelectChangeEventDetail>) => void;
     /**
-     * Emitted when the dropdown is toggled.
+     * Emitted when the dropdown opens or closes, with the new open state in the event detail.
      */
     onToggle?: (event: CustomEvent<MultiSelectToggleEventDetail>) => void;
     /**
-     * Requires an option with a non-empty string value to be selected.
+     * Marks the multi-select as required — form submission is blocked unless at least one option is selected.
      * @default false
      */
     required?: boolean;
     /**
-     * The validation state.
+     * Sets the validation state, controlling the visual appearance and style of the feedback message (`none`, `success`, `error`).
      * @default 'none'
      */
     state?: MultiSelectState;

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

@@ -1,23 +1,23 @@
 import type { BaseProps } from '../../BaseProps';
 export type POptgroupProps = BaseProps & {
     /**
-     * Disables the optgroup.
+     * Disables all options in the group, preventing any of them from being selected.
      * @default false
      */
     disabled?: boolean;
     /**
-     * The optgroup label.
+     * Sets the visible group heading displayed above the grouped options.
      */
     label?: string;
 };
 export declare const POptgroup: 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 optgroup.
+     * Disables all options in the group, preventing any of them from being selected.
      * @default false
      */
     disabled?: boolean;
     /**
-     * The optgroup label.
+     * Sets the visible group heading displayed above the grouped options.
      */
     label?: string;
 } & {

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

@@ -2,62 +2,62 @@ import type { BaseProps } from '../../BaseProps';
 import type { PaginationInternationalization, PaginationUpdateEventDetail } from '../types';
 export type PPaginationProps = BaseProps & {
     /**
-     * Index of the currently active page.
+     * Sets the one-based index of the currently active page; update this prop to navigate programmatically.
      * @default 1
      */
     activePage: number;
     /**
-     * Override the default wordings that are used for aria-labels on the next/prev and page buttons.
+     * Overrides the default ARIA label strings used for the previous, next, and page number buttons to support localisation.
      * @default {   root: 'Pagination',   prev: 'Previous page',   next: 'Next page',   page: 'Page',   }
      */
     intl?: PaginationInternationalization;
     /**
-     * The total count of items which should be shown per page.
+     * Sets the number of items displayed per page, used together with `totalItemsCount` to compute the page count.
      * @default 1
      */
     itemsPerPage?: number;
     /**
-     * Emitted when the page changes.
+     * Emitted when the user navigates to a different page, carrying the new `activePage` index in the event detail.
      */
     onUpdate?: (event: CustomEvent<PaginationUpdateEventDetail>) => void;
     /**
-     * Show or hide the button to jump to the last page.
+     * Shows or hides the button that jumps directly to the last page of the pagination.
      * @default true
      */
     showLastPage?: boolean;
     /**
-     * The total count of items.
+     * Sets the total number of items in the dataset, used to calculate the number of pages.
      * @default 1
      */
     totalItemsCount: number;
 };
 export declare const PPagination: 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"> & {
     /**
-     * Index of the currently active page.
+     * Sets the one-based index of the currently active page; update this prop to navigate programmatically.
      * @default 1
      */
     activePage: number;
     /**
-     * Override the default wordings that are used for aria-labels on the next/prev and page buttons.
+     * Overrides the default ARIA label strings used for the previous, next, and page number buttons to support localisation.
      * @default {   root: 'Pagination',   prev: 'Previous page',   next: 'Next page',   page: 'Page',   }
      */
     intl?: PaginationInternationalization;
     /**
-     * The total count of items which should be shown per page.
+     * Sets the number of items displayed per page, used together with `totalItemsCount` to compute the page count.
      * @default 1
      */
     itemsPerPage?: number;
     /**
-     * Emitted when the page changes.
+     * Emitted when the user navigates to a different page, carrying the new `activePage` index in the event detail.
      */
     onUpdate?: (event: CustomEvent<PaginationUpdateEventDetail>) => void;
     /**
-     * Show or hide the button to jump to the last page.
+     * Shows or hides the button that jumps directly to the last page of the pagination.
      * @default true
      */
     showLastPage?: boolean;
     /**
-     * The total count of items.
+     * Sets the total number of items in the dataset, used to calculate the number of pages.
      * @default 1
      */
     totalItemsCount: number;