@porsche-design-system/components-react 3.10.0-rc.3 → 3.10.0-rc.5

package/ssr/cjs/components/dist/styles/esm/styles-entry.cjs

@@ -29,20 +29,20 @@ function _typeof(o) {
   }, _typeof(o);
 }
 
-function _toPrimitive(input, hint) {
-  if (_typeof(input) !== "object" || input === null) return input;
-  var prim = input[Symbol.toPrimitive];
-  if (prim !== undefined) {
-    var res = prim.call(input, hint || "default");
-    if (_typeof(res) !== "object") return res;
+function toPrimitive(t, r) {
+  if ("object" != _typeof(t) || !t) return t;
+  var e = t[Symbol.toPrimitive];
+  if (void 0 !== e) {
+    var i = e.call(t, r || "default");
+    if ("object" != _typeof(i)) return i;
     throw new TypeError("@@toPrimitive must return a primitive value.");
   }
-  return (hint === "string" ? String : Number)(input);
+  return ("string" === r ? String : Number)(t);
 }
 
-function _toPropertyKey(arg) {
-  var key = _toPrimitive(arg, "string");
-  return _typeof(key) === "symbol" ? key : String(key);
+function toPropertyKey(t) {
+  var i = toPrimitive(t, "string");
+  return "symbol" == _typeof(i) ? i : String(i);
 }
 
 function _defineProperties(target, props) {
@@ -51,7 +51,7 @@ function _defineProperties(target, props) {
     descriptor.enumerable = descriptor.enumerable || false;
     descriptor.configurable = true;
     if ("value" in descriptor) descriptor.writable = true;
-    Object.defineProperty(target, _toPropertyKey(descriptor.key), descriptor);
+    Object.defineProperty(target, toPropertyKey(descriptor.key), descriptor);
   }
 }
 function _createClass(Constructor, protoProps, staticProps) {
@@ -3221,7 +3221,7 @@ const getFocusStyle = (opts) => {
             ? borderRadiusMedium
             : borderRadius || borderRadiusSmall;
     return {
-        borderRadius: borderRadiusValue,
+        borderRadius: borderRadiusValue, // it's visually being reflected on both (when placed here), element and focus outline
         '&:focus': {
             outline: `${borderWidthBase} solid ${themeLightStateFocus}`,
             outlineOffset,
@@ -3855,7 +3855,7 @@ const getInsetJssStyle = (value = 0) => {
 const getResetInitialStylesForSlottedAnchor = {
     margin: 0,
     padding: 0,
-    outline: 0,
+    outline: 0, // reset native blue outline
     borderRadius: 0,
     background: 'transparent',
 };
@@ -3868,7 +3868,7 @@ const focusPseudoJssStyle = {
         ...getInsetJssStyle(),
     },
     '&:focus::before': {
-        borderRadius: '1px',
+        borderRadius: '1px', // TODO: why just 1px border-radius?
         outline: `${borderWidthBase} solid ${themeLightStateFocus}`,
         outlineOffset: '2px',
     },
@@ -3911,35 +3911,36 @@ const getBackfaceVisibilityJssStyle = () => ({
 /**
  * Generates JSS styles for a frosted glass background.
  * @param {boolean} isVisible - Determines if the frosted glass effect is visible.
+ * @param {number} zIndex - The z-index to be used.
+ * @param {Theme} theme - The theme to be used.
  * @param {string} duration - The duration of the transition animation.
- * @param {Theme} theme - The theme to be used
- * @param {string} timingFn - The timing function of the transition animation. (default: 'cubic-bezier(.16,1,.3,1)')
- * @returns {JssStyle} - The JSS styles for the frosted glass background.
+ * @returns {JssStyle} - The JSS styles for the frosted glass backdrop.
  */
-const getFrostedGlassBackgroundJssStyles = (isVisible, duration, theme) => {
+const getBackdropJssStyle = (isVisible, zIndex, theme, duration = 'long') => {
     return {
-        // workaround via pseudo element to fix stacking (black) background in safari
-        '&::before': {
-            content: '""',
-            position: 'fixed',
-            ...getInsetJssStyle(),
-            background: isThemeDark(theme) ? themeDarkBackgroundShading : themeLightBackgroundShading,
-            pointerEvents: 'none',
-            ...(isVisible
-                ? {
-                    opacity: 1,
-                    ...frostedGlassStyle,
-                }
-                : {
-                    opacity: 0,
-                    backdropFilter: 'blur(0px)',
-                    WebkitBackdropFilter: 'blur(0px)',
-                }),
-            transition: `${getTransition('opacity', duration, 'base')}, ${getTransition('backdrop-filter', duration, 'base')}, ${getTransition('-webkit-backdrop-filter', duration, 'base')}`,
-            ...prefersColorSchemeDarkMediaQuery(theme, {
-                background: themeDarkBackgroundShading,
+        position: 'fixed',
+        ...getInsetJssStyle(),
+        zIndex,
+        // TODO: background shading is missing in getThemedColors(theme).backgroundShading
+        background: isThemeDark(theme) ? themeDarkBackgroundShading : themeLightBackgroundShading,
+        ...prefersColorSchemeDarkMediaQuery(theme, {
+            background: themeDarkBackgroundShading,
+        }),
+        ...(isVisible
+            ? {
+                visibility: 'inherit',
+                pointerEvents: 'auto',
+                ...frostedGlassStyle,
+                opacity: 1,
+            }
+            : {
+                visibility: 'hidden', // element shall not be tabbable after fade out transition has finished
+                pointerEvents: 'none',
+                WebkitBackdropFilter: 'blur(0px)',
+                backdropFilter: 'blur(0px)',
+                opacity: 0,
             }),
-        },
+        transition: `${getTransition('opacity', duration)}, ${getTransition('backdrop-filter', duration)}, ${getTransition('-webkit-backdrop-filter', duration)}, visibility 0s linear var(${cssVariableTransitionDuration}, ${isVisible ? '0s' : motionDurationMap[duration]})`,
     };
 };
 
@@ -4098,12 +4099,14 @@ const getComponentCss$13 = (size, compact, open, theme) => {
             ':host': {
                 display: 'block',
                 ...addImportantToEachRule({
-                    ...(!compact && {
-                        borderBottom: `1px solid ${contrastLowColor}`,
-                        ...prefersColorSchemeDarkMediaQuery(theme, {
-                            borderColor: contrastLowColorDark,
+                    ...(compact
+                        ? { transform: 'translate3d(0,0,0)' } // relevant for custom click-area in compact variant
+                        : {
+                            borderBottom: `1px solid ${contrastLowColor}`,
+                            ...prefersColorSchemeDarkMediaQuery(theme, {
+                                borderColor: contrastLowColorDark,
+                            }),
                         }),
-                    }),
                     '&(:only-of-type)': { borderBottom: 0 },
                     ...colorSchemeStyles,
                     ...hostHiddenStyles,
@@ -4113,11 +4116,12 @@ const getComponentCss$13 = (size, compact, open, theme) => {
                 display: 'flex',
                 position: 'relative',
                 justifyContent: 'space-between',
+                alignItems: 'center',
                 width: '100%',
                 textDecoration: 'none',
                 border: 0,
                 outline: 0,
-                margin: 0,
+                margin: 0, // Removes default button margin on safari 15
                 gap: '24px',
                 background: 'transparent',
                 cursor: 'pointer',
@@ -4190,7 +4194,7 @@ const getComponentCss$13 = (size, compact, open, theme) => {
             transition: getTransition('transform'),
         },
         collapsible: {
-            color: primaryColor,
+            color: primaryColor, // enables color inheritance for slotted content
             ...prefersColorSchemeDarkMediaQuery(theme, {
                 color: primaryColorDark,
             }),
@@ -4198,7 +4202,7 @@ const getComponentCss$13 = (size, compact, open, theme) => {
             ...(open
                 ? {
                     gridTemplateRows: '1fr',
-                    visibility: 'visible',
+                    visibility: 'inherit',
                     transition: getTransition('grid-template-rows'),
                     paddingBottom: compact ? spacingStaticSmall : '24px',
                 }
@@ -4244,10 +4248,10 @@ const getComponentCss$12 = (isOpen) => {
                 margin: 0,
                 padding: 0,
                 width: 'auto',
-                maxWidth: '100%',
+                maxWidth: '100%', // If component is wrapped in container with maxWidth
                 zIndex: `var(${cssVariableZIndex},${BANNER_Z_INDEX})`,
                 ...dropShadowHighStyle,
-                borderRadius: borderRadiusSmall,
+                borderRadius: borderRadiusSmall, // needed for rounded box-shadow
                 ...(isOpen
                     ? {
                         opacity: 1,
@@ -4355,14 +4359,14 @@ const getLinkButtonPureStyles = (icon, iconSource, active, isDisabledOrLoading,
         '@global': {
             ':host': {
                 ...addImportantToEachRule({
-                    transform: 'translate3d(0,0,0)',
-                    outline: 0,
+                    transform: 'translate3d(0,0,0)', // creates new stacking context
+                    outline: 0, // custom element is able to delegate the focus
                     ...colorSchemeStyles,
                     ...hostHiddenStyles,
                 }),
                 ...buildResponsiveStyles(stretch, (responsiveStretch) => ({
                     display: responsiveStretch ? 'block' : 'inline-block',
-                    width: responsiveStretch ? '100%' : 'auto',
+                    width: responsiveStretch ? '100%' : 'auto', // prevents adjusting its size when used as flex or grid child
                     ...(!responsiveStretch && { verticalAlign: 'top' }),
                 })),
             },
@@ -4372,7 +4376,7 @@ const getLinkButtonPureStyles = (icon, iconSource, active, isDisabledOrLoading,
             gap: spacingStaticXSmall,
             width: '100%',
             padding: 0,
-            margin: 0,
+            margin: 0, // Removes default button margin on safari 15
             color: isDisabledOrLoading ? disabledColor : primaryColor,
             ...prefersColorSchemeDarkMediaQuery(theme, {
                 color: isDisabledOrLoading ? disabledColorDark : primaryColorDark,
@@ -4387,7 +4391,7 @@ const getLinkButtonPureStyles = (icon, iconSource, active, isDisabledOrLoading,
             }))),
             '&::before': {
                 content: '""',
-                position: 'absolute',
+                position: 'absolute', // mobile Safari -> prevent lagging active state
                 top: offsetVertical,
                 bottom: offsetVertical,
                 ...buildResponsiveStyles(hideLabel, (hideLabelValue) => ({
@@ -4454,7 +4458,7 @@ const getComponentCss$10 = (icon, iconSource, active, isLoading, isDisabledOrLoa
     const hasIcon = hasVisibleIcon(icon, iconSource);
     return getCss(mergeDeep(getLinkButtonPureStyles(icon, iconSource, active, isDisabledOrLoading, stretch, size, hideLabel, alignLabel, false, theme), {
         root: {
-            WebkitAppearance: 'none',
+            WebkitAppearance: 'none', // iOS safari
             appearance: 'none',
             background: 'transparent',
             textAlign: 'start',
@@ -4488,18 +4492,17 @@ const getFontWeight = (weight) => {
 
 const getThemedTypographyColor = (theme, textColor // eslint-disable-line @typescript-eslint/no-duplicate-type-constituents
 ) => {
-    // TODO: don't destructure for better minification
-    const { primaryColor, contrastHighColor, contrastMediumColor, contrastLowColor, successColor, errorColor, warningColor, infoColor, } = getThemedColors(theme);
+    const themedColors = getThemedColors(theme);
     const colorMap = {
-        primary: primaryColor,
-        default: primaryColor,
-        'contrast-low': contrastLowColor,
-        'contrast-medium': contrastMediumColor,
-        'contrast-high': contrastHighColor,
-        'notification-success': successColor,
-        'notification-warning': warningColor,
-        'notification-error': errorColor,
-        'notification-info': infoColor,
+        primary: themedColors.primaryColor,
+        default: themedColors.primaryColor, // deprecated but part of HeadlineColor
+        'contrast-low': themedColors.contrastLowColor,
+        'contrast-medium': themedColors.contrastMediumColor,
+        'contrast-high': themedColors.contrastHighColor,
+        'notification-success': themedColors.successColor,
+        'notification-warning': themedColors.warningColor,
+        'notification-error': themedColors.errorColor,
+        'notification-info': themedColors.infoColor,
         inherit: 'currentColor',
     };
     return colorMap[textColor];
@@ -4540,7 +4543,7 @@ const getTileBaseStyles = (aspectRatio, isDisabled) => {
         root: {
             position: 'relative',
             overflow: 'hidden',
-            transform: 'translate3d(0,0,0)',
+            transform: 'translate3d(0,0,0)', // change stacking context for position fixed
             borderRadius: borderRadiusLarge,
             color: getThemedTypographyColor('dark', 'primary'),
             ...buildResponsiveStyles(aspectRatio, (ratio) => ({
@@ -4565,7 +4568,7 @@ const getTileBaseStyles = (aspectRatio, isDisabled) => {
             display: 'flex',
             justifyItems: 'start',
             gap: spacingStaticMedium,
-            borderRadius: borderRadiusLarge,
+            borderRadius: borderRadiusLarge, // for gradient
             '@media (forced-colors: active)': {
                 background: 'rgba(0,0,0,0.7)',
             },
@@ -4583,7 +4586,7 @@ background, align, compact, hasGradient, isDisabled) => {
     return mergeDeep(getTileBaseStyles(aspectRatio, isDisabled), {
         '@global': {
             p: {
-                maxWidth: pxToRemWithUnit(550),
+                maxWidth: pxToRemWithUnit(550), // in this case rem unit makes sense to scale up available space
                 margin: 0,
                 ...textLargeStyle,
                 hyphens: 'inherit',
@@ -4596,7 +4599,7 @@ background, align, compact, hasGradient, isDisabled) => {
             },
         },
         content: {
-            display: 'grid',
+            display: 'grid', // TODO: flex via getTileBaseStyles
             ...(isTopAligned ? { top: 0 } : { bottom: 0 }),
             padding: isTopAligned
                 ? `${spacingFluidMedium} ${spacingFluidMedium} ${spacingFluidLarge}`
@@ -4619,7 +4622,7 @@ background, align, compact, hasGradient, isDisabled) => {
             display: isCompact ? 'inline-block' : 'none',
         })),
         'link-or-button': {
-            minHeight: '54px',
+            minHeight: '54px', // prevent content shift
             ...buildResponsiveStyles(compact, (isCompact) => ({
                 display: isCompact ? 'none' : 'inline-block',
             })),
@@ -4673,7 +4676,7 @@ const getLinkButtonStyles = (icon, iconSource, variant, hideLabel, isDisabledOrL
                 display: 'inline-block',
                 ...addImportantToEachRule({
                     verticalAlign: 'top',
-                    outline: 0,
+                    outline: 0, // custom element is able to delegate the focus
                     ...colorSchemeStyles,
                     ...hostHiddenStyles,
                 }),
@@ -4684,17 +4687,17 @@ const getLinkButtonStyles = (icon, iconSource, variant, hideLabel, isDisabledOrL
             alignItems: 'flex-start',
             justifyContent: 'center',
             width: '100%',
-            minWidth: '54px',
-            minHeight: '54px',
+            minWidth: '54px', // ensure space is already reserved until icon component is loaded (ssr)
+            minHeight: '54px', // ensure space is already reserved until icon component is loaded (ssr)
             boxSizing: 'border-box',
             outline: 0,
             textAlign: 'start',
-            WebkitAppearance: 'none',
+            WebkitAppearance: 'none', // iOS safari
             appearance: 'none',
             textDecoration: 'none',
             border: `2px solid ${borderColor}`,
             borderRadius: borderRadiusSmall,
-            transform: 'translate3d(0,0,0)',
+            transform: 'translate3d(0,0,0)', // creates new stacking context (for slotted anchor + focus)
             backgroundColor,
             color: textColor,
             ...textSmallStyle,
@@ -4823,19 +4826,15 @@ const bulletInfiniteClass = 'bullet--infinite';
 const paginationBulletSize = '8px';
 const paginationInfiniteBulletSize = '4px';
 const paginationActiveBulletSize = '20px';
-const selectorHeading = 'h2,::slotted([slot=heading])';
-const selectorDescription = 'p,::slotted([slot=description])';
+const selectorHeading = 'h2,::slotted([slot="heading"])';
+const selectorDescription = 'p,::slotted([slot="description"])';
 const mediaQueryS = getMediaQueryMin('s');
 const mediaQueryXXL = getMediaQueryMin('xxl');
-// we need an explicit grid template, therefor we need to calculate the button group width
-const buttonSize$1 = `calc(${spacingStaticSmall} * 2 + ${fontLineHeight})`;
-// + 2px, compensates hover offset of button-pure
-const buttonGroupWidth = `calc(${buttonSize$1} * 3 + ${spacingStaticXSmall} + 2px)`;
 const spacingMap = {
     basic: gridBasicOffset,
     extended: gridExtendedOffset,
 };
-const getComponentCss$Z = (width, hasPagination, isInfinitePagination, alignHeader, theme) => {
+const getComponentCss$Z = (hasHeading, hasDescription, hasControlsSlot, headingSize, width, hasPagination, isInfinitePagination, alignHeader, theme) => {
     const { primaryColor, contrastMediumColor, focusColor } = getThemedColors(theme);
     const { primaryColor: primaryColorDark, contrastMediumColor: contrastMediumColorDark, focusColor: focusColorDark, } = getThemedColors('dark');
     const { canvasTextColor } = getHighContrastColors();
@@ -4845,13 +4844,21 @@ const getComponentCss$Z = (width, hasPagination, isInfinitePagination, alignHead
             ':host': {
                 display: 'flex',
                 ...addImportantToEachRule({
-                    gap: spacingFluidMedium,
+                    gap: spacingFluidMedium, // TODO: maybe it's better to style by margin on .splide, then styles would be part of shadow dom
                     flexDirection: 'column',
-                    boxSizing: 'content-box',
+                    boxSizing: 'content-box', // ensures padding is added to host instead of subtracted
                     ...colorSchemeStyles,
                     ...hostHiddenStyles,
                 }),
             },
+            ...(hasControlsSlot && {
+                ['slot[name="controls"]']: {
+                    display: 'block',
+                    gridColumnStart: 1,
+                    gridRowStart: 3,
+                    alignSelf: 'center', // ensures vertical alignment to prev/next buttons
+                },
+            }),
             ...addImportantToEachRule({
                 '::slotted(*)': {
                     borderRadius: `var(--p-carousel-border-radius, ${borderRadiusLarge})`,
@@ -4863,45 +4870,45 @@ const getComponentCss$Z = (width, hasPagination, isInfinitePagination, alignHead
                     }),
                     outlineOffset: '2px',
                 },
-                [selectorHeading]: {
-                    ...headingXLargeStyle,
-                    maxWidth: '56.25rem',
-                    margin: 0,
-                },
-                [selectorDescription]: {
-                    ...textSmallStyle,
-                    maxWidth: '34.375rem',
-                    margin: `${spacingFluidXSmall} 0 0`,
-                },
-                [`${selectorHeading},${selectorDescription}`]: {
-                    color: primaryColor,
-                    ...prefersColorSchemeDarkMediaQuery(theme, {
-                        color: primaryColorDark,
-                    }),
-                    [mediaQueryS]: isHeaderAlignCenter
-                        ? {
-                            gridColumn: 2,
-                        }
-                        : {
-                            gridColumn: '1 / 3',
-                        },
-                },
+                // TODO: maybe it's better to style with slot[name="heading"] and slot[name="description"] instead, then styles would be part of shadow dom
+                // h2,::slotted([slot=heading]),p,::slotted([slot=description])
+                ...((hasHeading || hasDescription) && {
+                    [`${selectorHeading},${selectorDescription}`]: {
+                        gridColumn: '1/-1',
+                        color: primaryColor,
+                        ...(isHeaderAlignCenter && {
+                            textAlign: 'center', // relevant in case heading or description becomes multiline
+                            justifySelf: 'center', // relevant for horizontal alignment of heading and description in case max-width applies
+                        }),
+                        ...prefersColorSchemeDarkMediaQuery(theme, {
+                            color: primaryColorDark,
+                        }),
+                    },
+                }),
+                // h2,::slotted([slot=heading])
+                ...(hasHeading && {
+                    [selectorHeading]: {
+                        maxWidth: '56.25rem',
+                        margin: `0 0 ${!hasDescription ? spacingFluidMedium : 0}`,
+                        ...(headingSize === 'xx-large' ? headingXXLargeStyle : headingXLargeStyle),
+                    },
+                }),
+                // p,::slotted([slot=description])
+                ...(hasDescription && {
+                    [selectorDescription]: {
+                        maxWidth: '34.375rem',
+                        margin: `${spacingFluidSmall} 0 ${spacingFluidMedium}`,
+                        ...textSmallStyle,
+                    },
+                }),
             }),
         },
         header: {
             display: 'grid',
             padding: `0 ${spacingMap[width].base}`,
-            ...(isHeaderAlignCenter && {
-                textAlign: 'center',
-            }),
             [mediaQueryS]: {
-                fontFamily,
-                fontSize: fontSizeTextSmall,
+                gridTemplateColumns: 'minmax(0px, 1fr) auto',
                 columnGap: spacingStaticMedium,
-                gridTemplateColumns: `${buttonGroupWidth} minmax(0px, 1fr) ${buttonGroupWidth}`,
-                ...(isHeaderAlignCenter && {
-                    justifyItems: 'center', // relevant when max-width of heading or description is reached
-                }),
                 padding: `0 ${spacingMap[width].s}`,
             },
             [mediaQueryXXL]: {
@@ -4911,12 +4918,11 @@ const getComponentCss$Z = (width, hasPagination, isInfinitePagination, alignHead
         nav: {
             display: 'none',
             [mediaQueryS]: {
+                gridRowStart: '3',
+                gridColumnEnd: '-1',
                 display: 'flex',
                 gap: spacingStaticXSmall,
-                gridArea: '1 / 3 / 3 / auto',
-                alignItems: 'end',
-                justifyContent: 'end',
-                justifySelf: 'end',
+                alignSelf: 'flex-start', // relevant in case slot="header" becomes higher than nav group
             },
         },
         btn: {
@@ -4932,8 +4938,8 @@ const getComponentCss$Z = (width, hasPagination, isInfinitePagination, alignHead
         },
         splide: {
             overflow: 'hidden',
-            padding: '4px 0',
-            margin: '-4px 0',
+            padding: '4px 0', // for slide focus outline
+            margin: '-4px 0', // for slide focus outline
             '&__track': {
                 // !important is necessary to override inline styles set by splide library
                 ...addImportantToEachRule({
@@ -4973,7 +4979,7 @@ const getComponentCss$Z = (width, hasPagination, isInfinitePagination, alignHead
                 })),
                 position: 'relative',
                 justifyContent: isInfinitePagination ? 'flex-start' : 'center',
-                width: `calc(${paginationActiveBulletSize} + ${paginationBulletSize} * 4 + ${spacingStaticSmall} * 4)`,
+                width: `calc(${paginationActiveBulletSize} + ${paginationBulletSize} * 4 + ${spacingStaticSmall} * 4)`, // Width for five bullets (one active + spacing)
                 left: 'calc(50% - 42px)',
                 overflowX: 'hidden',
             },
@@ -4981,7 +4987,7 @@ const getComponentCss$Z = (width, hasPagination, isInfinitePagination, alignHead
                 display: 'flex',
                 alignItems: 'center',
                 width: 'fit-content',
-                height: paginationBulletSize,
+                height: paginationBulletSize, // Needed to avoid jumping when rewinding dynamically added slides
                 gap: spacingStaticSmall,
                 transition: `transform ${carouselTransitionDuration}`,
             },
@@ -5096,14 +5102,14 @@ const getSlottedCheckboxRadioButtonStyles = (state, isDisabled, isLoading, theme
     return {
         '::slotted': {
             '&(input)': {
-                position: 'relative',
+                position: 'relative', // TODO: can be removed as soon as focus style was adjusted
                 width: fontLineHeight,
                 height: fontLineHeight,
-                font: `${fontSizeTextSmall} ${fontFamily}`,
+                font: `${fontSizeTextSmall} ${fontFamily}`, // needed for correct width and height definition based on ex-unit
                 display: 'block',
                 margin: 0,
                 padding: 0,
-                WebkitAppearance: 'none',
+                WebkitAppearance: 'none', // iOS safari
                 appearance: 'none',
                 boxSizing: 'content-box',
                 background: `transparent 0% 0% / ${fontLineHeight}`,
@@ -5193,9 +5199,9 @@ const getFunctionalComponentLabelStyles = (isDisabledOrLoading, hideLabel, theme
         label: {
             ...textSmallStyle,
             cursor: isDisabledOrLoading ? 'not-allowed' : 'pointer',
-            justifySelf: 'flex-start',
+            justifySelf: 'flex-start', // ensures label is not getting stretched by flex or grid context of its parent
             color: isDisabledOrLoading ? disabledColor : primaryColor,
-            transition: getTransition('color'),
+            transition: getTransition('color'), // for smooth transitions between e.g. disabled state
             ...buildResponsiveStyles(hideLabel, (isHidden) => getHiddenTextJssStyle(isHidden, additionalIsShownJssStyle)),
             ...prefersColorSchemeDarkMediaQuery(theme, {
                 color: isDisabledOrLoading ? disabledColorDark : primaryColorDark,
@@ -5304,7 +5310,7 @@ const getComponentCss$Y = (hideLabel, state, isDisabled, isLoading, theme) => {
         wrapper: {
             display: 'grid',
             gridArea: '1/1',
-            alignSelf: 'flex-start',
+            alignSelf: 'flex-start', // in case label becomes multiline
             ...(isDisabledOrLoading(isDisabled, isLoading) && {
                 // TODO: maybe .wrapper should handle it for all form components while pointer-events: none is set to input
                 cursor: 'not-allowed',
@@ -5313,12 +5319,12 @@ const getComponentCss$Y = (hideLabel, state, isDisabled, isLoading, theme) => {
         ...(isLoading && {
             // TODO: extract for checkbox-wrapper and radio-button-wrapper (not gridArea and placeSelf)
             spinner: {
-                position: 'relative',
+                position: 'relative', // ensure correct stacking, can be removed as soon as focus for input is handled with outline
                 gridArea: '1/1',
                 placeSelf: 'center',
                 width: fontLineHeight,
                 height: fontLineHeight,
-                font: `${fontSizeTextSmall} ${fontFamily}`,
+                font: `${fontSizeTextSmall} ${fontFamily}`, // needed for correct width and height definition based on ex-unit
                 pointerEvents: 'none',
             },
         }),
@@ -5326,7 +5332,7 @@ const getComponentCss$Y = (hideLabel, state, isDisabled, isLoading, theme) => {
         ...getFunctionalComponentLabelStyles(isDisabled || isLoading, hideLabel, theme, {
             gridArea: '1/2',
         }, {
-            paddingTop: '2px',
+            paddingTop: '2px', // compensate vertical alignment
             paddingInlineStart: spacingStaticSmall, // asymmetric padding used instead of gap to prevent not clickable area between label and input
         }),
         // .message
@@ -5353,7 +5359,7 @@ const getComponentCss$X = (width) => {
             },
         },
         root: {
-            minWidth: 0,
+            minWidth: 0, // needed for some flex context
             ...(['full', 'fluid'].includes(width)
                 ? {
                     padding: `0 ${gridFullOffset}`,
@@ -5392,7 +5398,7 @@ const getComponentCss$W = () => {
                 verticalAlign: 'top',
                 ...addImportantToEachRule({
                     outline: 0,
-                    boxSizing: 'content-box',
+                    boxSizing: 'content-box', // needed for correct height calculation when padding is set on host (e.g. custom click area)
                     ...getDimensionStyle,
                     ...colorSchemeStyles,
                     ...hostHiddenStyles,
@@ -5681,7 +5687,7 @@ const getComponentCss$P = (isPrimaryScrollerVisible, isSecondaryScrollerVisible,
                         [cssVariableVisibility]: 'hidden',
                         [cssVariableVisibilityTransitionDuration]: motionDurationLong,
                     }),
-                    ...getBackdropJssStyle(isPrimaryScrollerVisible, 'long', theme),
+                    ...getBackdropJssStyle(isPrimaryScrollerVisible, FLYOUT_Z_INDEX, theme),
                     ...colorSchemeStyles,
                     ...hostHiddenStyles,
                 }),
@@ -5689,17 +5695,17 @@ const getComponentCss$P = (isPrimaryScrollerVisible, isSecondaryScrollerVisible,
             dialog: {
                 position: 'fixed',
                 ...getInsetJssStyle(),
-                display: 'grid',
-                width: 'auto',
-                height: '100vh',
-                maxWidth: '100vw',
-                maxHeight: '100vh',
-                margin: 0,
-                padding: 0,
-                border: 0,
-                visibility: 'inherit',
-                background: 'none',
-                overflow: 'hidden',
+                display: 'grid', // ua-style reset
+                width: 'auto', // ua-style reset and to ensure transition duration works correctly
+                height: '100vh', // ua-style reset
+                maxWidth: '100vw', // ua-style reset
+                maxHeight: '100vh', // ua-style reset
+                margin: 0, // ua-style reset
+                padding: 0, // ua-style reset
+                border: 0, // ua-style reset
+                visibility: 'inherit', // ua-style reset
+                background: 'none', // ua-style reset
+                overflow: 'hidden', // ua-style reset, dialog shall never become scrollable, it's handled by custom scroll areas
                 ...(isPrimaryScrollerVisible
                     ? {
                         transform: 'translate3d(0, 0, 0)',
@@ -5734,7 +5740,7 @@ const getComponentCss$P = (isPrimaryScrollerVisible, isSecondaryScrollerVisible,
             overflow: 'auto',
             // cssVariableVisibility ensures secondary scroller is not tabbable when whole flyout-navigation is closed
             // on mobile we need to decide if secondary scroller needs to be visible or not, on desktop it's not necessary but also doesn't harm
-            visibility: `var(${cssVariableVisibility},${isSecondaryScrollerVisible ? 'hidden' : 'visible'})`,
+            visibility: `var(${cssVariableVisibility},${isSecondaryScrollerVisible ? 'hidden' : 'inherit'})`,
             transition: `${getTransition('left', 'long', isSecondaryScrollerVisible ? 'in' : 'out')}, visibility 0s linear var(${cssVariableTransitionDuration}, ${!isPrimaryScrollerVisible || isSecondaryScrollerVisible ? motionDurationLong : '0s'})`,
             // it's important to define background-color for each scroller to have correct scrollbar coloring
             backgroundColor,
@@ -5755,7 +5761,7 @@ const getComponentCss$P = (isPrimaryScrollerVisible, isSecondaryScrollerVisible,
                 height: frostedGlassHeaderHeight,
                 backgroundColor: frostedGlassBackgroundColor,
                 WebkitBackdropFilter: 'blur(8px)',
-                backdropFilter: 'blur(8px)',
+                backdropFilter: 'blur(8px)', // with current frostedGlassStyle of blur(32px) scrolling becomes visually distracting
                 ...prefersColorSchemeDarkMediaQuery(theme, {
                     backgroundColor: frostedGlassBackgroundColorDark$1,
                 }),
@@ -5776,7 +5782,7 @@ const getComponentCss$P = (isPrimaryScrollerVisible, isSecondaryScrollerVisible,
         // header is needed to keep position of dismiss button in sync with header of secondary scroller
         header: {
             position: 'relative',
-            zIndex: 3,
+            zIndex: 3, // ensures dismiss button is visible on secondary drawer in mobile view
             gridArea: '1/1',
             alignSelf: 'flex-start',
             justifySelf: 'flex-end',
@@ -5800,40 +5806,6 @@ const getComponentCss$P = (isPrimaryScrollerVisible, isSecondaryScrollerVisible,
         },
     });
 };
-// TODO: getBackdropJssStyle can be shared with flyout and modal
-/**
- * Generates JSS styles for a frosted glass background.
- * @param {boolean} isVisible - Determines if the frosted glass effect is visible.
- * @param {string} duration - The duration of the transition animation.
- * @param {Theme} theme - The theme to be used
- * @returns {JssStyle} - The JSS styles for the frosted glass backdrop.
- */
-const getBackdropJssStyle = (isVisible, duration, theme) => {
-    return {
-        position: 'fixed',
-        ...getInsetJssStyle(),
-        zIndex: FLYOUT_Z_INDEX,
-        ...(isVisible
-            ? {
-                visibility: 'visible',
-                pointerEvents: 'auto',
-                ...frostedGlassStyle,
-                // TODO: background shading is missing in getThemedColors(theme).backgroundShading
-                background: isThemeDark(theme) ? themeDarkBackgroundShading : themeLightBackgroundShading,
-                ...prefersColorSchemeDarkMediaQuery(theme, {
-                    background: themeDarkBackgroundShading,
-                }),
-            }
-            : {
-                visibility: 'hidden',
-                pointerEvents: 'none',
-                WebkitBackdropFilter: 'blur(0px)',
-                backdropFilter: 'blur(0px)',
-                background: 'none',
-            }),
-        transition: `${getTransition('background', duration, 'base')}, ${getTransition('backdrop-filter', duration, 'base')}, ${getTransition('-webkit-backdrop-filter', duration, 'base')}, visibility 0s linear var(${cssVariableTransitionDuration}, ${isVisible ? '0s' : motionDurationLong})`,
-    };
-};
 const getContentJssStyle = () => {
     return {
         display: 'flex',
@@ -5952,6 +5924,7 @@ const getComponentCss$O = (isSecondaryScrollerVisible, theme) => {
                 ? {
                     zIndex: 2,
                     transform: 'translate3d(0, 0, 0)',
+                    // TODO: Should be visibility: inherit to allow overwriting but currently not possible since it would inherit from the scroller of the p-flyout-navigation itself, which is hidden on mobile
                     visibility: `var(${cssVariableVisibility},visible)`,
                     transition: `${getTransition('transform', 'long', 'in')}, visibility 0s linear var(${cssVariableTransitionDuration},var(${cssVariableVisibilityTransitionDuration},0s))`,
                 }
@@ -5972,9 +5945,9 @@ const getComponentCss$O = (isSecondaryScrollerVisible, theme) => {
             }),
             [mediaQueryEnhancedView]: {
                 boxShadow: 'none',
-                insetInlineStart: `calc(${scrollerWidthEnhancedView} - 1px)`,
+                insetInlineStart: `calc(${scrollerWidthEnhancedView} - 1px)`, // -1px prevents possible visible background under certain circumstances between primary and secondary scroller
                 width: scrollerWidthEnhancedView,
-                transform: addImportantToRule('initial'),
+                transform: addImportantToRule('initial'), // to overrule :dir(rtl) selector
                 transition: `visibility 0s linear var(${cssVariableTransitionDuration},var(${cssVariableVisibilityTransitionDuration},0s))`,
             },
             '&:dir(rtl)': {
@@ -5995,7 +5968,7 @@ const getComponentCss$O = (isSecondaryScrollerVisible, theme) => {
             alignItems: 'center',
             gap: spacingFluidSmall,
             WebkitBackdropFilter: 'blur(8px)',
-            backdropFilter: 'blur(8px)',
+            backdropFilter: 'blur(8px)', // with current frostedGlassStyle of blur(32px) scrolling becomes visually distracting
             backgroundColor: frostedGlassBackgroundColor,
             ...fadeInOutTransition,
             ...prefersColorSchemeDarkMediaQuery(theme, {
@@ -6046,19 +6019,9 @@ const getComponentCss$N = (isOpen, position, hasFooter, hasSubFooter, theme) =>
                     // needed for correct alignment of the Porsche Grid within the Flyout
                     '--pds-internal-grid-outer-column': `calc(${spacingFluidLarge} - ${gridGap})`,
                     '--pds-internal-grid-margin': `calc(${spacingFluidLarge} * -1)`,
-                    position: 'fixed',
-                    zIndex: FLYOUT_Z_INDEX,
                     justifyContent: isPositionStart ? 'flex-start' : 'flex-end',
-                    ...(isOpen
-                        ? {
-                            visibility: 'inherit',
-                        }
-                        : {
-                            visibility: 'hidden',
-                            transition: `visibility 0s linear var(${cssVariableTransitionDuration}, ${motionDurationLong})`,
-                        }),
                     ...getInsetJssStyle(),
-                    ...getFrostedGlassBackgroundJssStyles(isOpen, 'long', theme),
+                    ...getBackdropJssStyle(isOpen, FLYOUT_Z_INDEX, theme),
                     ...colorSchemeStyles,
                     ...hostHiddenStyles,
                 }),
@@ -6077,7 +6040,7 @@ const getComponentCss$N = (isOpen, position, hasFooter, hasSubFooter, theme) =>
             height: '100%',
             minWidth: '320px',
             maxWidth: 'var(--p-flyout-max-width, 1180px)',
-            color: primaryColor,
+            color: primaryColor, // enables color inheritance for slotted content
             background: backgroundColor,
             ...(isOpen
                 ? {
@@ -6124,7 +6087,7 @@ const getComponentCss$N = (isOpen, position, hasFooter, hasSubFooter, theme) =>
             padding: contentPadding,
             position: 'relative',
             zIndex: 0,
-            backgroundColor,
+            backgroundColor, // to ensure scrollbar coloring is optimal for light theme
             ...prefersColorSchemeDarkMediaQuery(theme, {
                 backgroundColor: backgroundColorDark, // to ensure scrollbar coloring is optimal for dark theme
             }),
@@ -6372,7 +6335,25 @@ const forceRerenderAnimationStyle = {
 const keyFramesLight = 'rerender-light';
 const keyFramesDark = 'rerender-dark';
 const cssVariableFilter = '--p-internal-icon-filter';
-const getComponentCss$I = (color, size, theme) => {
+const isFlippableIcon = (name, source) => {
+    return (!source &&
+        (name === 'arrow-double-left' ||
+            name === 'arrow-double-right' ||
+            name === 'arrow-first' ||
+            name === 'arrow-head-left' ||
+            name === 'arrow-head-right' ||
+            name === 'arrow-last' ||
+            name === 'arrow-left' ||
+            name === 'arrow-right' ||
+            name === 'chart' ||
+            name === 'chat' ||
+            name === 'external' ||
+            name === 'increase' ||
+            name === 'list' ||
+            name === 'logout' ||
+            name === 'send'));
+};
+const getComponentCss$I = (name, source, color, size, theme) => {
     const isColorInherit = color === 'inherit';
     const isSizeInherit = size === 'inherit';
     const isDark = isThemeDark(theme);
@@ -6387,10 +6368,10 @@ const getComponentCss$I = (color, size, theme) => {
                 }),
             },
             img: {
-                display: 'block',
+                display: 'block', // without display, img tag gets some extra spacing
                 margin: 0,
                 padding: 0,
-                pointerEvents: 'none',
+                pointerEvents: 'none', // disable dragging/ghosting of images
                 ...(!isColorInherit && {
                     filter: `var(${cssVariableFilter},${filterMap[theme][color]})`,
                     ...prefersColorSchemeDarkMediaQuery(theme, {
@@ -6414,6 +6395,11 @@ const getComponentCss$I = (color, size, theme) => {
                         height: fontLineHeight,
                         font: `${sizeMap$2[size]} ${fontFamily}`,
                     }),
+                ...(isFlippableIcon(name, source) && {
+                    '&:dir(rtl)': {
+                        transform: 'scaleX(-1)',
+                    },
+                }),
             },
             ...(!isColorInherit && {
                 [`@keyframes ${isDark ? keyFramesDark : keyFramesLight}-${color}`]: forceRerenderAnimationStyle,
@@ -6427,7 +6413,7 @@ const mediaQueryMaxS$2 = getMediaQueryMax('s');
 const getBackgroundColor = (state, theme) => {
     const { infoSoftColor, successSoftColor, errorSoftColor, warningSoftColor } = getThemedColors(theme);
     const colorMap = {
-        neutral: infoSoftColor,
+        neutral: infoSoftColor, // deprecated
         info: infoSoftColor,
         warning: warningSoftColor,
         success: successSoftColor,
@@ -6641,7 +6627,7 @@ const getComponentCss$E = (aspectRatio, weight, direction, hasDescription) => {
         },
         ...(hasDescription && {
             description: {
-                margin: '-12px 0 0 ',
+                margin: '-12px 0 0 ', // TODO: perhaps gap should be overridden instead
                 ...textSmallStyle,
                 hyphens: 'inherit',
             },
@@ -6664,7 +6650,7 @@ const slottedAnchorSelector = `a[slot='${anchorSlot}']`;
 const anchorJssStyle = {
     position: 'absolute',
     ...getInsetJssStyle(),
-    zIndex: 1,
+    zIndex: 1, // necessary to be on top of img
     borderRadius: borderRadiusMedium,
 };
 const getMultilineEllipsis = (lineClamp) => {
@@ -6682,7 +6668,7 @@ const getComponentCss$D = (hasLikeButton, hasSlottedAnchor, aspectRatio, theme)
         '@global': {
             ':host': {
                 display: 'block',
-                position: 'relative',
+                position: 'relative', // needed for ::slotted(a) to overlay correctly
                 ...addImportantToEachRule({
                     ...colorSchemeStyles,
                     ...hostHiddenStyles,
@@ -6730,7 +6716,7 @@ const getComponentCss$D = (hasLikeButton, hasSlottedAnchor, aspectRatio, theme)
             display: 'flex',
             flexDirection: 'column',
             aspectRatio: '3/4',
-            overflow: 'hidden',
+            overflow: 'hidden', // TODO: discussable if we should prevent text to overflow .root, – e.g. it also prevents a popover from being shown correctly
             boxSizing: 'border-box',
             borderRadius: borderRadiusMedium,
             padding: spacingFluidSmall,
@@ -6796,7 +6782,7 @@ const getComponentCss$D = (hasLikeButton, hasSlottedAnchor, aspectRatio, theme)
         description: {
             ...textXXSmallStyle,
             ...getMultilineEllipsis(2),
-            margin: 0,
+            margin: 0, // ua-style reset
             color: contrastHighColor,
             ...prefersColorSchemeDarkMediaQuery(theme, {
                 color: contrastHighColorDark,
@@ -6877,8 +6863,8 @@ const getFullscreenJssStyles = (fullscreen) => {
             borderRadius: 0,
         }
         : {
-            minWidth: '276px',
-            maxWidth: '1535.5px',
+            minWidth: '276px', // on viewport 320px: calc(${gridColumnWidthBase} * 6 + ${gridGap} * 5)
+            maxWidth: '1535.5px', // on viewport 1920px: `calc(${gridColumnWidthXXL} * 14 + ${gridGap} * 13)`
             minHeight: 'auto',
             margin: `${marginTopBottom} ${gridExtendedOffsetBase}`,
             borderRadius: borderRadiusMedium,
@@ -6923,26 +6909,11 @@ const getComponentCss$A = (isOpen, isFullscreen, hasDismissButton, hasHeader, ha
     return getCss({
         '@global': {
             ':host': {
-                display: 'flex',
-                overflowY: 'auto',
+                overflowY: 'auto', // overrideable
                 ...addImportantToEachRule({
-                    position: 'fixed',
-                    ...getInsetJssStyle(),
-                    zIndex: MODAL_Z_INDEX,
-                    alignItems: 'center',
-                    justifyContent: 'center',
-                    flexWrap: 'wrap',
-                    ...(isOpen
-                        ? {
-                            visibility: 'inherit',
-                        }
-                        : {
-                            visibility: 'hidden',
-                            transition: `visibility 0s linear var(${cssVariableTransitionDuration}, ${motionDurationShort})`,
-                        }),
                     ...colorSchemeStyles,
                     ...hostHiddenStyles,
-                    ...getFrostedGlassBackgroundJssStyles(isOpen, duration, theme),
+                    ...getBackdropJssStyle(isOpen, MODAL_Z_INDEX, theme, duration),
                 }),
             },
             '::slotted': addImportantToEachRule(mergeDeep(getSlottedJssStyle(32, hasHeader, hasDismissButton), buildResponsiveStyles(isFullscreen, (fullscreenValue) => ({
@@ -6964,14 +6935,23 @@ const getComponentCss$A = (isOpen, isFullscreen, hasDismissButton, hasHeader, ha
                 }),
             },
         },
+        'scroll-container': {
+            display: 'flex',
+            ...getInsetJssStyle(),
+            height: '100%',
+            overflowY: 'inherit',
+            alignItems: 'center',
+            justifyContent: 'center',
+            flexWrap: 'wrap',
+        },
         root: mergeDeep({
-            color: primaryColor,
+            color: primaryColor, // enables color inheritance for slotted content
             position: 'relative',
             boxSizing: 'border-box',
             transform: isOpen ? 'translateY(0%)' : 'translateY(25%)',
             opacity: isOpen ? 1 : 0,
             transition: `${getTransition('opacity', duration, easing)}, ${getTransition('transform', duration, easing)}`,
-            paddingTop: hasDismissButton ? pxToRemWithUnit(32) : contentPadding,
+            paddingTop: hasDismissButton ? pxToRemWithUnit(32) : contentPadding, // rem value needed to prevent overlapping of close button and contents in scaling mode
             ...(!hasFooter && { paddingBottom: contentPadding }),
             background: backgroundColor,
             outline: isHighContrastMode ? '1px solid transparent' : 0,
@@ -6980,7 +6960,7 @@ const getComponentCss$A = (isOpen, isFullscreen, hasDismissButton, hasHeader, ha
                 content: '""',
                 position: 'fixed',
                 border: `${borderWidthBase} solid`,
-                pointerEvents: 'none',
+                pointerEvents: 'none', // fix text selection in focus state
                 ...buildResponsiveStyles(isFullscreen, (fullscreenValue) => ({
                     borderRadius: fullscreenValue ? 0 : '12px',
                     borderColor: fullscreenValue ? primaryColor : darkThemePrimaryColor,
@@ -7009,7 +6989,7 @@ const getComponentCss$A = (isOpen, isFullscreen, hasDismissButton, hasHeader, ha
         }),
         content: {
             ...(hasFooter && {
-                position: 'relative',
+                position: 'relative', // to make sure content isn't above sticky footer, but might affect consumer's absolute positioning
                 zIndex: 0,
             }),
             padding: `0 ${contentPadding}`,
@@ -7028,7 +7008,7 @@ const getComponentCss$A = (isOpen, isFullscreen, hasDismissButton, hasHeader, ha
             },
             [footerShadowClass]: {
                 boxShadow: `${isThemeDark(theme) ? scrollShadowColorDark : scrollShadowColor} 0 -5px 10px`,
-                clipPath: 'inset(-20px 0 0 0)',
+                clipPath: 'inset(-20px 0 0 0)', // crop leaking box-shadow on left and right side
                 ...prefersColorSchemeDarkMediaQuery(theme, {
                     boxShadow: `${scrollShadowColorDark} 0 -5px 10px`,
                 }),
@@ -7042,9 +7022,10 @@ const getComponentCss$A = (isOpen, isFullscreen, hasDismissButton, hasHeader, ha
                 left: '8px',
                 display: 'flex',
                 justifyContent: 'flex-end',
+                zIndex: 1, // To assure controls are on top when using stretchToFullModalWidthClassName and transformed slotted content
             },
             dismiss: {
-                border: `2px solid ${backgroundColor}`,
+                border: `2px solid ${backgroundColor}`, // needed to enlarge button slightly without affecting the hover area (are equal now).
                 borderRadius: '4px',
                 background: backgroundColor,
                 ...hoverMediaQuery({
@@ -7106,7 +7087,7 @@ const getComponentCss$z = (size, color, theme) => {
                 display: 'block',
                 maxWidth: '100%',
                 maxHeight: '100%',
-                pointerEvents: 'none',
+                pointerEvents: 'none', // prevents image drag
                 ...(!isColorInherit && {
                     filter: colorToFilterMap[theme][color],
                     ...prefersColorSchemeDarkMediaQuery(theme, {
@@ -7132,7 +7113,7 @@ const getComponentCss$y = (theme) => {
     return getCss({
         '@global': {
             ':host': addImportantToEachRule({
-                scrollMarginTop: spacingStaticSmall,
+                scrollMarginTop: spacingStaticSmall, // Creates top margin when navigating with keyboard and list is scrolled automatically
                 ...hostHiddenStyles,
             }),
         },
@@ -7225,16 +7206,16 @@ const getSlottedTextFieldTextareaSelectStyles = (child, state, isLoading, theme,
                 : 'auto',
             margin: 0,
             outline: 0,
-            WebkitAppearance: 'none',
+            WebkitAppearance: 'none', // iOS safari
             appearance: 'none',
             boxSizing: 'border-box',
             border: `${borderWidthBase} solid ${formStateColor || contrastMediumColor}`,
             borderRadius: borderRadiusSmall,
             background: 'transparent',
-            font: textSmallStyle.font.replace('ex', 'ex + 6px'),
+            font: textSmallStyle.font.replace('ex', 'ex + 6px'), // a minimum line-height is needed for input, otherwise value is scrollable in Chrome, +6px is aligned with how Safari visualize date/time input highlighting
             textIndent: 0,
             color: primaryColor,
-            transition: `${getTransition('background-color')}, ${getTransition('border-color')}, ${getTransition('color')}`,
+            transition: `${getTransition('background-color')}, ${getTransition('border-color')}, ${getTransition('color')}`, // for smooth transitions between e.g. disabled states
             ...prefersColorSchemeDarkMediaQuery(theme, {
                 borderColor: formStateColorDark || contrastMediumColorDark,
                 color: primaryColorDark,
@@ -7357,7 +7338,7 @@ const getComponentCss$x = (direction, isOpen, isDisabled, hideLabel, state, isWi
             placeSelf: 'center',
             padding: formButtonOrIconPadding,
             pointerEvents: 'none',
-            transform: 'rotate3d(0,0,1,0.0001deg)',
+            transform: 'rotate3d(0,0,1,0.0001deg)', // needs to be a little more than 0 for correct direction in safari
             transition: getTransition('transform'),
             '&--rotate': {
                 transform: 'rotate3d(0,0,1,180deg)',
@@ -7400,26 +7381,26 @@ const getInputStyles = (isDisabled, direction, isOpen, state, theme) => {
         flex: 1,
         minWidth: 0,
         // TODO: abstract and re-use for multi-select, select-wrapper and text-field-wrapper
-        height: `calc(${fontLineHeight} + 10px + ${borderWidthBase} * 2 + ${spacingStaticSmall} * 2)`,
-        font: textSmallStyle.font.replace('ex', 'ex + 6px'),
-        margin: 0,
+        height: `calc(${fontLineHeight} + 10px + ${borderWidthBase} * 2 + ${spacingStaticSmall} * 2)`, // we need 10px additionally so input height becomes 54px, // we need 6px additionally so input height becomes 50px
+        font: textSmallStyle.font.replace('ex', 'ex + 6px'), // a minimum line-height is needed for input, otherwise value is scrollable in Chrome, +6px is alig
+        margin: 0, // necessary reset for iOS Safari 15 (and maybe other browsers)
         padding: `${formElementPaddingVertical} ${formElementPaddingHorizontal}`,
         paddingInlineEnd: getCalculatedFormElementPaddingHorizontal(2),
         boxSizing: 'border-box',
         outline: 0,
-        WebkitAppearance: 'none',
+        WebkitAppearance: 'none', // iOS safari
         appearance: 'none',
         ...textSmallStyle,
         textOverflow: 'ellipsis',
         '&:disabled': {
             cursor: 'not-allowed',
         },
-        transition: `${getTransition('background-color')}, ${getTransition('border-color')}, ${getTransition('color')}`,
+        transition: `${getTransition('background-color')}, ${getTransition('border-color')}, ${getTransition('color')}`, // for smooth transitions between e.g. disabled states
         color: primaryColor,
         '&:not(:focus)': {
             ...getPlaceholderJssStyle({ color: primaryColor, opacity: 1 }),
             ...prefersColorSchemeDarkMediaQuery(theme, getPlaceholderJssStyle({ color: primaryColorDark, opacity: 1 })),
-        },
+        }, // Opacity fixes placeholder being shown lighter in firefox
         ...hoverMediaQuery({
             '&:hover:not(:disabled):not(:focus),label:hover~.wrapper &:not(:disabled):not(:focus)': {
                 borderColor: isOpen ? primaryColor : formStateHoverColor || primaryColor,
@@ -7440,7 +7421,7 @@ const getInputStyles = (isDisabled, direction, isOpen, state, theme) => {
         border: `${borderWidthBase} solid ${isOpen ? primaryColor : formStateColor || contrastMediumColor}`,
         borderRadius: borderRadiusSmall,
         ...(isOpen && {
-            [isDirectionDown ? 'paddingBottom' : 'paddingTop']: `calc(${formElementPaddingVertical} + 1px)`,
+            [isDirectionDown ? 'paddingBottom' : 'paddingTop']: `calc(${formElementPaddingVertical} + 1px)`, // Add padding to keep same height when border changes
             [isDirectionDown ? 'borderBottom' : 'borderTop']: addImportantToRule(`1px solid ${contrastMediumColor}`),
             [isDirectionDown ? 'borderBottomLeftRadius' : 'borderTopLeftRadius']: 0,
             [isDirectionDown ? 'borderBottomRightRadius' : 'borderTopRightRadius']: 0,
@@ -7485,7 +7466,7 @@ const getListStyles$1 = (isOpen, direction, theme) => {
         right: 0,
         [isDirectionDown ? 'top' : 'bottom']: '100%',
         boxSizing: 'border-box',
-        maxHeight: `${8.5 * (MULTI_SELECT_OPTION_HEIGHT + 8) + 6 + 2}px`,
+        maxHeight: `${8.5 * (MULTI_SELECT_OPTION_HEIGHT + 8) + 6 + 2}px`, // 8.5 options * option height + 8px gap + additional spacing (6px = padding, 2px = border)
         overflowY: 'auto',
         WebkitOverflowScrolling: 'touch',
         background: backgroundColor,
@@ -7494,10 +7475,10 @@ const getListStyles$1 = (isOpen, direction, theme) => {
         borderRadius: borderRadiusSmall,
         [isDirectionDown ? 'borderTopLeftRadius' : 'borderBottomLeftRadius']: 0,
         [isDirectionDown ? 'borderTopRightRadius' : 'borderBottomRightRadius']: 0,
-        scrollbarWidth: 'thin',
-        scrollbarColor: 'auto',
+        scrollbarWidth: 'thin', // firefox
+        scrollbarColor: 'auto', // firefox
         transition: getTransition('border-color'),
-        transform: 'translate3d(0,0,0)',
+        transform: 'translate3d(0,0,0)', // fix iOS bug if less than 5 items are displayed
         ...prefersColorSchemeDarkMediaQuery(theme, {
             background: backgroundColorDark,
             borderColor: primaryColorDark,
@@ -7586,7 +7567,7 @@ const getComponentCss$w = (activePage, pageTotal, showLastPage, theme) => {
                 display: 'flex',
                 justifyContent: 'center',
                 alignItems: 'center',
-                transition: `${getTransition('background-color')}, ${getTransition('border-color')}, ${getTransition('color')}`,
+                transition: `${getTransition('background-color')}, ${getTransition('border-color')}, ${getTransition('color')}`, // for smooth transition between states
                 position: 'relative',
                 width: buttonSize,
                 height: buttonSize,
@@ -7597,7 +7578,7 @@ const getComponentCss$w = (activePage, pageTotal, showLastPage, theme) => {
                 color: primaryColor,
                 outline: 0,
                 borderRadius: borderRadiusSmall,
-                borderColor: 'transparent',
+                borderColor: 'transparent', // default value is needed for smooth transition
                 ...prefersColorSchemeDarkMediaQuery(theme, {
                     color: primaryColorDark,
                 }),
@@ -7676,12 +7657,21 @@ const getComponentCss$v = (hideLabel, state, isDisabled, isLoading, isWithinForm
         }),
         // TODO: move into getSlottedTextFieldTextareaSelectStyles() via parameter, e.g. isLoading
         ...(isLoading && {
-            opacity: 0.2,
+            opacity: 0.2, // TODO: not in sync with e.g. checkbox/radio-button loading style
             cursor: 'not-allowed',
         }),
-        ...Object.fromEntries(Array.from(Array(length)).map((_, i) => {
+        // since @playwright/test@1.40.1 this does not work anymore in Webkit browser engine for unknown reasons
+        /* ...Object.fromEntries(
+          Array.from(Array(length)).map((_, i) => {
             return [`&:nth-of-type(${i + 1})`, { gridArea: `1/${i + 1}` }];
-        })),
+          })
+        ),*/
+        '&:nth-of-type(1)': { gridArea: '1/1' },
+        '&:nth-of-type(2)': { gridArea: '1/2' },
+        '&:nth-of-type(3)': { gridArea: '1/3' },
+        '&:nth-of-type(4)': { gridArea: '1/4' },
+        '&:nth-of-type(5)': { gridArea: '1/5' },
+        '&:nth-of-type(6)': { gridArea: '1/6' },
     })));
     return getCss({
         '@global': {
@@ -7710,12 +7700,13 @@ const getComponentCss$v = (hideLabel, state, isDisabled, isLoading, isWithinForm
         },
         wrapper: {
             display: 'grid',
+            gridTemplateColumns: `repeat(${length}, minmax(0, 1fr))`,
             justifySelf: 'flex-start',
             gap: spacingStaticSmall,
         },
         ...(isLoading && {
             spinner: {
-                gridArea: `1/1/1/${length + 1}`,
+                gridArea: '1/1/1/-1',
                 placeSelf: 'center',
                 width: inputSize,
                 height: inputSize,
@@ -7850,7 +7841,7 @@ const getComponentCss$u = (direction, isNative, theme) => {
             button: {
                 display: 'block',
                 position: 'relative',
-                WebkitAppearance: 'none',
+                WebkitAppearance: 'none', // iOS safari
                 appearance: 'none',
                 background: 'transparent',
                 border: 0,
@@ -7858,8 +7849,8 @@ const getComponentCss$u = (direction, isNative, theme) => {
                 outline: 0,
                 cursor: 'pointer',
                 ...textSmallStyle,
-                width: fontLineHeight,
-                height: fontLineHeight,
+                width: fontLineHeight, // width needed to improve ssr support
+                height: fontLineHeight, // height needed to improve ssr support
                 borderRadius: '50%',
                 ...hoverMediaQuery({
                     transition: getTransition('background-color'),
@@ -7891,7 +7882,6 @@ const getComponentCss$u = (direction, isNative, theme) => {
         },
         label: getHiddenTextJssStyle(),
         icon: {
-            display: 'inline-block',
             transform: 'translate3d(0,0,0)', // Fixes movement on hover in Safari
         },
         spacer: {
@@ -7907,7 +7897,7 @@ const getComponentCss$u = (direction, isNative, theme) => {
             position: 'absolute',
             zIndex: POPOVER_Z_INDEX,
             filter: `drop-shadow(0 0 16px ${shadowColor})`,
-            backdropFilter: 'drop-shadow(0px 0px 0px transparent)',
+            backdropFilter: 'drop-shadow(0px 0px 0px transparent)', // fixes issues with Chrome >= 105 where filter: drop-shadow is not applied correctly after animation ends
             pointerEvents: 'none',
             animation: `${motionDurationShort} $fadeIn ${motionEasingBase} forwards`
                 ,
@@ -8005,7 +7995,7 @@ const getComponentCss$t = (hideLabel, state, isDisabled, isLoading, theme) => {
         wrapper: {
             display: 'grid',
             gridArea: '1/1',
-            alignSelf: 'flex-start',
+            alignSelf: 'flex-start', // in case label becomes multiline
             ...(isDisabledOrLoading(isDisabled, isLoading) && {
                 // TODO: maybe .wrapper should handle it for all form components while pointer-events: none is set to input
                 cursor: 'not-allowed',
@@ -8014,12 +8004,12 @@ const getComponentCss$t = (hideLabel, state, isDisabled, isLoading, theme) => {
         ...(isLoading && {
             // TODO: extract for checkbox-wrapper and radio-button-wrapper (not gridArea and placeSelf)
             spinner: {
-                position: 'relative',
+                position: 'relative', // ensure correct stacking, can be removed as soon as focus for input is handled with outline
                 gridArea: '1/1',
                 placeSelf: 'center',
                 width: fontLineHeight,
                 height: fontLineHeight,
-                font: `${fontSizeTextSmall} ${fontFamily}`,
+                font: `${fontSizeTextSmall} ${fontFamily}`, // needed for correct width and height definition based on ex-unit
                 pointerEvents: 'none',
             },
         }),
@@ -8027,7 +8017,7 @@ const getComponentCss$t = (hideLabel, state, isDisabled, isLoading, theme) => {
         ...getFunctionalComponentLabelStyles(isDisabled || isLoading, hideLabel, theme, {
             gridArea: '1/2',
         }, {
-            paddingTop: '2px',
+            paddingTop: '2px', // compensate vertical alignment
             paddingInlineStart: spacingStaticSmall, // asymmetric padding used instead of gap to prevent not clickable area between label and input
         }),
         // .message
@@ -8187,38 +8177,43 @@ const getComponentCss$s = (gradientColor, isNextHidden, isPrevHidden, scrollIndi
         },
         'action-prev': {
             ...actionPrevNextStyles,
-            left: '-1px',
+            left: '-1px', // ensures that the gradient always overlays the content (e.g. when zoomed)
             justifyContent: 'flex-start',
             background: `linear-gradient(to right, ${getGradient(theme, gradientColor)} 100%)`,
             ...prefersColorSchemeDarkMediaQuery(theme, {
                 background: `linear-gradient(to right, ${getGradient('dark', gradientColor)} 100%)`,
             }),
-            visibility: isPrevHidden ? 'hidden' : 'visible',
+            visibility: isPrevHidden ? 'hidden' : 'inherit',
             '& button': {
                 marginLeft: '8px',
                 // hide buttons on mobile (actually devices not supporting hover)
                 ...hoverMediaQuery({
-                    visibility: isPrevHidden ? 'hidden' : 'visible',
+                    visibility: isPrevHidden ? 'hidden' : 'inherit',
                 }),
             },
         },
         'action-next': {
             ...actionPrevNextStyles,
-            right: '-1px',
+            right: '-1px', // ensures that the gradient always overlays the content (e.g. when zoomed)
             justifyContent: 'flex-end',
             background: `linear-gradient(to left, ${getGradient(theme, gradientColor)} 100%)`,
             ...prefersColorSchemeDarkMediaQuery(theme, {
                 background: `linear-gradient(to left, ${getGradient('dark', gradientColor)} 100%)`,
             }),
-            visibility: isNextHidden ? 'hidden' : 'visible',
+            visibility: isNextHidden ? 'hidden' : 'inherit',
             '& button': {
                 marginRight: '8px',
                 // hide buttons on mobile (actually devices not supporting hover)
                 ...hoverMediaQuery({
-                    visibility: isNextHidden ? 'hidden' : 'visible',
+                    visibility: isNextHidden ? 'hidden' : 'inherit',
                 }),
             },
         },
+        icon: {
+            '&:dir(rtl)': {
+                transform: 'scaleX(-1)',
+            },
+        },
     });
 };
 
@@ -8257,7 +8252,7 @@ const getComponentCss$r = (isDisabled, isSelected, hasIcon, hasSlottedContent, t
                 height: '100%',
                 width: '100%',
                 padding: getItemPadding(hasIcon && hasSlottedContent),
-                margin: 0,
+                margin: 0, // Removes default button margin on safari 15
                 border: `${borderWidthBase} solid ${borderColor}`,
                 borderRadius: borderRadiusSmall,
                 outline: 0,
@@ -8334,7 +8329,7 @@ const getComponentCss$q = (maxWidth, columns) => {
             ':host': {
                 display: 'grid',
                 ...addImportantToEachRule({
-                    gridAutoRows: '1fr',
+                    gridAutoRows: '1fr', // for equal height
                     ...buildResponsiveStyles(columns, (col) => ({
                         gridTemplateColumns: col === 'auto' ? `repeat(auto-fit, ${maxWidth}px)` : `repeat(${col}, minmax(0, 1fr))`,
                     })),
@@ -8360,16 +8355,16 @@ const getButtonStyles = (direction, isOpen, state, theme) => {
             button: {
                 position: 'absolute',
                 ...getInsetJssStyle(),
-                width: '100%',
-                height: '100%',
+                width: '100%', // fixes Firefox positioning issue
+                height: '100%', // fixes Firefox positioning issue
                 margin: 0,
                 padding: 0,
                 background: 'transparent',
-                border: `${borderWidthBase} solid ${isOpen ? primaryColor : formStateColor || contrastMediumColor}`,
+                border: `${borderWidthBase} solid ${isOpen ? primaryColor : formStateColor || contrastMediumColor}`, // using border of styled select below for label:hover selector
                 borderRadius: borderRadiusSmall,
                 outline: '0',
                 cursor: 'pointer',
-                transition: getTransition('border-color'),
+                transition: getTransition('border-color'), // background and text color are handled on select
                 ...prefersColorSchemeDarkMediaQuery(theme, {
                     borderColor: isOpen ? primaryColorDark : formStateColorDark || contrastMediumColorDark,
                 }),
@@ -8421,23 +8416,23 @@ const getFilterStyles = (direction, isOpen, state, disabled, theme) => {
             input: {
                 display: 'block',
                 position: 'absolute',
-                ...getInsetJssStyle(2),
-                width: 'calc(100% - 4px)',
-                height: 'calc(100% - 4px)',
+                ...getInsetJssStyle(2), // 2 = borderWidthBase
+                width: 'calc(100% - 4px)', // fixes Firefox positioning issue, 4px = 2 x borderWidthBase
+                height: 'calc(100% - 4px)', // fixes Firefox positioning issue, 4px = 2 x borderWidthBase
                 zIndex: 1,
-                font: textSmallStyle.font.replace('ex', 'ex + 6px'),
-                margin: 0,
+                font: textSmallStyle.font.replace('ex', 'ex + 6px'), // a minimum line-height is needed for input, otherwise value is scrollable in Chrome, +6px is alig
+                margin: 0, // necessary reset for iOS Safari 15 (and maybe other browsers)
                 // TODO: could be done with css subgrid much more elegant in the near future
                 //  or move input into select-wrapper and handle it the same like multi-select
                 padding: `${formElementPaddingVertical} ${formElementPaddingHorizontal}`,
                 paddingInlineEnd: getCalculatedFormElementPaddingHorizontal(1),
                 outline: '0',
-                WebkitAppearance: 'none',
+                WebkitAppearance: 'none', // iOS safari
                 appearance: 'none',
                 boxSizing: 'border-box',
-                border: '0',
-                borderRadius: borderRadiusSmall,
-                opacity: 0,
+                border: '0', // done via span
+                borderRadius: borderRadiusSmall, // for white corners
+                opacity: 0, // is used to overlay input on focus
                 ...textSmallStyle,
                 textIndent: 0,
                 cursor: disabled ? 'not-allowed' : 'text',
@@ -8460,7 +8455,7 @@ const getFilterStyles = (direction, isOpen, state, disabled, theme) => {
                     ...prefersColorSchemeDarkMediaQuery(theme, placeHolderDarkJssStyle),
                 },
                 '&:not(:disabled):focus': {
-                    opacity: 1,
+                    opacity: 1, // to display value while typing
                     '&+span, &~ ul': {
                         borderColor: primaryColor,
                         ...prefersColorSchemeDarkMediaQuery(theme, {
@@ -8519,7 +8514,7 @@ const getListStyles = (direction, theme) => {
                 display: 'flex',
                 flexDirection: 'column',
                 gap: spacingStaticSmall,
-                position: `var(${dropdownPositionVar}, absolute)`,
+                position: `var(${dropdownPositionVar}, absolute)`, // for vrt tests
                 padding: '6px',
                 margin: 0,
                 background: backgroundColor,
@@ -8528,9 +8523,9 @@ const getListStyles = (direction, theme) => {
                 zIndex: 10,
                 left: 0,
                 right: 0,
-                [isDirectionDown ? 'top' : 'bottom']: 'calc(100% - 2px)',
+                [isDirectionDown ? 'top' : 'bottom']: 'calc(100% - 2px)', // 2px border + 2px safety for rounded corners
                 boxSizing: 'border-box',
-                maxHeight: `${8.5 * (OPTION_HEIGHT + 8) + 6 + 2}px`,
+                maxHeight: `${8.5 * (OPTION_HEIGHT + 8) + 6 + 2}px`, // 8px = gap, 6px = padding, 2px = border
                 overflowY: 'auto',
                 WebkitOverflowScrolling: 'touch',
                 scrollBehavior: 'smooth',
@@ -8539,10 +8534,10 @@ const getListStyles = (direction, theme) => {
                 ...(isDirectionDown
                     ? ['borderBottomLeftRadius', 'borderBottomRightRadius']
                     : ['borderTopLeftRadius', 'borderTopRightRadius']).reduce((result, curr) => ({ ...result, [curr]: borderRadiusSmall }), {}),
-                scrollbarWidth: 'thin',
-                scrollbarColor: 'auto',
+                scrollbarWidth: 'thin', // firefox
+                scrollbarColor: 'auto', // firefox
                 transition: getTransition('border-color'),
-                transform: 'translate3d(0,0,0)',
+                transform: 'translate3d(0,0,0)', // fix iOS bug if less than 5 items are displayed
                 ...prefersColorSchemeDarkMediaQuery(theme, {
                     color: contrastHighColorDark,
                     background: backgroundColorDark,
@@ -8646,7 +8641,7 @@ const getComponentCss$p = (direction, isOpen, state, disabled, filter, isNativeP
                 margin: 0,
                 overflow: 'initial',
                 height: 'auto',
-                maxHeight: `${8.5 * (OPTION_HEIGHT + 8) + 6 + 2}px`,
+                maxHeight: `${8.5 * (OPTION_HEIGHT + 8) + 6 + 2}px`, // 8px = gap, 6px = padding, 2px = border
                 '&:-internal-popover-in-top-layer::backdrop': {
                     display: 'none',
                 },
@@ -8671,7 +8666,7 @@ const getComponentCss$o = (isDisabled, hasCustomDropdown, hideLabel, state, them
             ...addImportantToEachRule(getSlottedTextFieldTextareaSelectStyles('select', state, false, theme, {
                 gridArea: '1/1/1/-1',
                 position: 'static',
-                zIndex: 0,
+                zIndex: 0, // TODO: overrides global style.css in e2e and vrts
                 cursor: 'pointer',
                 // TODO: move into getSlottedTextFieldTextareaSelectStyles()
                 padding: `${formElementPaddingVertical} ${formElementPaddingHorizontal}`,
@@ -8693,10 +8688,10 @@ const getComponentCss$o = (isDisabled, hasCustomDropdown, hideLabel, state, them
             gridArea: '1/2',
             placeSelf: 'center',
             position: 'relative',
-            zIndex: 2,
+            zIndex: 2, // ensures icon is above input or button of select dropdown
             pointerEvents: 'none',
             padding: formButtonOrIconPadding,
-            transform: 'rotate3d(0,0,1,0.0001deg)',
+            transform: 'rotate3d(0,0,1,0.0001deg)', // needs to be a little more than 0 for correct direction in safari
             transition: getTransition('transform'),
             '&--open': {
                 transform: 'rotate3d(0,0,1,180deg)',
@@ -8740,7 +8735,7 @@ const getComponentCss$n = (size, theme) => {
                 }),
             },
             svg: {
-                display: 'block',
+                display: 'block', // for correct vertical alignment
                 fill: 'none',
                 animation: `$rotate ${animationDuration} steps(50) infinite`,
             },
@@ -8859,7 +8854,7 @@ const getComponentCss$m = (state, disabled, theme) => {
                 gap: '3px',
                 color: isDisabled ? disabledColor : primaryColor,
                 padding: '4px 10px 4px 6px',
-                margin: 0,
+                margin: 0, // Removes default button margin on safari 15
                 background: 0,
                 border: 0,
                 outline: 0,
@@ -8982,11 +8977,11 @@ const getComponentCss$k = (alignLabel, hideLabel, stretch, checked, disabled, lo
                     display: stretchValue ? 'block' : 'inline-block',
                 })),
                 ...addImportantToEachRule({
-                    outline: 0,
+                    outline: 0, // custom element is able to delegate the focus
                     ...colorSchemeStyles,
                     ...hostHiddenStyles,
                     ...buildResponsiveStyles(stretch, (stretchValue) => ({
-                        width: stretchValue ? '100%' : 'auto',
+                        width: stretchValue ? '100%' : 'auto', // prevents adjusting its size when used as flex or grid child
                         ...(!stretchValue && { verticalAlign: 'top' }),
                     })),
                 }),
@@ -8998,12 +8993,12 @@ const getComponentCss$k = (alignLabel, hideLabel, stretch, checked, disabled, lo
             gap: spacingStaticSmall,
             width: '100%',
             padding: 0,
-            margin: 0,
+            margin: 0, // Removes default button margin on safari 15
             outline: 0,
             border: 0,
             textAlign: 'start',
             background: 'transparent',
-            WebkitAppearance: 'none',
+            WebkitAppearance: 'none', // iOS safari
             appearance: 'none',
             cursor: isDisabledOrLoading(disabled, loading) ? 'auto' : 'pointer',
             ...buildResponsiveStyles(stretch, (stretchValue) => ({
@@ -9082,8 +9077,8 @@ const getComponentCss$k = (alignLabel, hideLabel, stretch, checked, disabled, lo
         }),
         label: {
             ...textSmallStyle,
-            minWidth: 0,
-            minHeight: 0,
+            minWidth: 0, // prevents flex child to overflow max available parent size
+            minHeight: 0, // prevents flex child to overflow max available parent size
             color: textColor,
             ...prefersColorSchemeDarkMediaQuery(theme, {
                 color: textColorDark,
@@ -9204,13 +9199,13 @@ const getComponentCss$g = (active, direction, hideLabel, multiline) => {
                         display: 'flex',
                         gap: spacingStaticXSmall,
                         width: 'auto',
-                        margin: 0,
+                        margin: 0, // Removes default button margin on safari 15
                         padding: 0,
                         font: 'inherit',
                         color: 'inherit',
                         outline: 0,
                         alignItems: 'flex-end',
-                        WebkitAppearance: 'none',
+                        WebkitAppearance: 'none', // iOS safari
                         appearance: 'none',
                         background: 'transparent',
                         textAlign: 'start',
@@ -9225,7 +9220,7 @@ const getComponentCss$g = (active, direction, hideLabel, multiline) => {
                             right: buttonBeforeOffsetHorizontal,
                             left: buttonBeforeOffsetHorizontal,
                             borderRadius: borderRadiusSmall,
-                            zIndex: -1,
+                            zIndex: -1, // needed so that text behind element is selectable and/or visible
                             transition: getTransition('background-color'),
                         },
                         ...hoverMediaQuery({
@@ -9260,7 +9255,7 @@ const getComponentCss$g = (active, direction, hideLabel, multiline) => {
                 transition: getTransition('opacity'),
                 opacity: active ? 1 : 0,
                 transform: `rotate3d(0,0,1,${isDirectionAsc(direction) ? 0 : 180}deg)`,
-                transformOrigin: '50% 50%',
+                transformOrigin: '50% 50%', // for iOS
                 filter: `var(${cssVariableTableHeadCellIconFilter})`,
             },
         }),
@@ -9364,7 +9359,7 @@ const getComponentCss$c = (size, weight, theme) => {
                     lineHeight: 'inherit',
                     whiteSpace: 'nowrap',
                     boxSizing: 'border-box',
-                    WebkitAppearance: 'none',
+                    WebkitAppearance: 'none', // iOS safari
                     appearance: 'none',
                     outlineOffset: '1px',
                     textDecoration: 'none',
@@ -9373,7 +9368,7 @@ const getComponentCss$c = (size, weight, theme) => {
                     color: primaryColor,
                     cursor: 'pointer',
                     borderRadius: borderRadiusSmall,
-                    zIndex: 0,
+                    zIndex: 0, // needed for ::before pseudo element to be visible
                     ...prefersColorSchemeDarkMediaQuery(theme, {
                         color: primaryColorDark,
                     }),
@@ -9383,7 +9378,7 @@ const getComponentCss$c = (size, weight, theme) => {
                             position: 'absolute',
                             inset: '-2px -4px',
                             borderRadius: borderRadiusSmall,
-                            zIndex: -1,
+                            zIndex: -1, // Stack the pseudo-element behind the button to avoid overlay of frosted-glass effect with label text
                             transition: getTransition('background-color'),
                         },
                     }),
@@ -9407,7 +9402,7 @@ const getComponentCss$c = (size, weight, theme) => {
                     ...barJssStyle,
                     right: '0px',
                     bottom: isHighContrastMode ? '-4px' : '-6px',
-                    visibility: 'visible',
+                    visibility: 'inherit',
                 },
                 // TODO: combine link-social-styles with link-button-styles and tabs-bar-styles
                 [transformSelector('::slotted([role]:focus:focus-visible)::before')]: {
@@ -9436,9 +9431,9 @@ const getComponentCss$c = (size, weight, theme) => {
         // moving bar
         bar: {
             ...barJssStyle,
-            width: 0,
+            width: 0, // actual width and transform is set via inline css
             bottom: isHighContrastMode ? '0' : '-2px',
-            visibility: 'visible',
+            visibility: 'inherit',
             transition: `${getTransition('transform', 'moderate')}, ${getTransition('width', 'moderate')}`,
             animation: `$hide 0s var(${cssVariableAnimationDuration},0.5s) forwards`, // auto hide bar after transition, needs to be a little longer in Safari
         },
@@ -9459,7 +9454,7 @@ const getComponentCss$b = (theme) => {
                 display: 'block',
                 ...addImportantToEachRule({
                     position: 'relative',
-                    color: primaryColor,
+                    color: primaryColor, // enables color inheritance for e.g. slotted anchor
                     outline: 0,
                     ...hostHiddenStyles,
                     ...prefersColorSchemeDarkMediaQuery(theme, {
@@ -9550,7 +9545,7 @@ const getComponentCss$9 = (color, hasLabel, theme) => {
                 gap: '12px',
                 minHeight: '54px',
                 padding: '4px 12px',
-                margin: 0,
+                margin: 0, // Removes default button margin on safari 15
                 borderRadius: borderRadiusSmall,
                 border: 0,
                 cursor: 'pointer',
@@ -9587,7 +9582,7 @@ const getComponentCss$9 = (color, hasLabel, theme) => {
         }),
         icon: {
             padding: '4px',
-            marginInlineEnd: '-2px',
+            marginInlineEnd: '-2px', // compensate white space of svg icon and optimize visual alignment
             transition: getTransition('background-color'),
             borderRadius: borderRadiusSmall,
         },
@@ -9672,7 +9667,7 @@ const getComponentCss$8 = (tagColor, isFocusable, theme) => {
                     cursor: 'pointer',
                     font: 'inherit',
                     color: 'inherit',
-                    WebkitAppearance: 'none',
+                    WebkitAppearance: 'none', // iOS safari
                     appearance: 'none',
                     border: 0,
                     textAlign: 'start',
@@ -9688,7 +9683,7 @@ const getComponentCss$8 = (tagColor, isFocusable, theme) => {
             }),
         },
         icon: {
-            marginInlineStart: '-2px',
+            marginInlineStart: '-2px', // compensate white space of svg icon and optimize visual alignment
             alignSelf: 'flex-start',
             ...(['neutral-contrast-high', 'primary'].includes(tagColor) && {
                 ...prefersColorSchemeDarkMediaQuery(theme, {
@@ -9738,8 +9733,8 @@ const getComponentCss$7 = (isDisabled, hideLabel, state, hasUnitOrVisibleCounter
                 ...getSlottedTextFieldTextareaSelectStyles('input', state, false, theme, {
                     gridArea: '1/1/1/-1',
                     padding: `${formElementPaddingVertical} ${formElementPaddingHorizontal}`,
-                    paddingInlineStart: `var(${cssVariableInputPaddingStart})`,
-                    paddingInlineEnd: `var(${cssVariableInputPaddingEnd})`,
+                    paddingInlineStart: `var(${cssVariableInputPaddingStart})`, // iOS Safari 14.5 can't handle padding-inline shorthand with css variables
+                    paddingInlineEnd: `var(${cssVariableInputPaddingEnd})`, // iOS Safari 14.5 can't handle padding-inline shorthand with css variables
                     // TODO: move into getSlottedTextFieldTextareaSelectStyles()
                     ...(isNumber && {
                         MozAppearance: 'textfield', // hides up/down spin button for Firefox
@@ -9789,8 +9784,7 @@ const getComponentCss$7 = (isDisabled, hideLabel, state, hasUnitOrVisibleCounter
             },
         }),
         ...(hasUnitOrVisibleCounter && {
-            // TODO: rename to unit-counter?
-            unit: {
+            'unit-counter': {
                 ...getUnitCounterJssStyle(isDisabled, theme),
                 gridArea: `1/${unitPosition === 'suffix' ? 5 : 1}/1/${unitPosition === 'suffix' ? 7 : 3}`,
                 placeSelf: 'center',
@@ -9844,8 +9838,8 @@ const getComponentCss$6 = (type, theme) => {
             },
             // css selector for text-list-item
             '::slotted(*)': addImportantToEachRule({
-                [cssVariablePaddingTop]: spacingStaticXSmall,
-                [cssVariablePaddingBottom]: spacingStaticMedium,
+                [cssVariablePaddingTop]: spacingStaticXSmall, // padding top for nested list
+                [cssVariablePaddingBottom]: spacingStaticMedium, // padding bottom for nested list, TODO: in case it's last root list item with a nested list it would result in outer spacing which is not desired
                 [cssVariablePseudoSpace]: isOrderedList
                     ? `var(${cssVariableOrderedGridColumn},1.5rem)`
                     : `var(${cssVariableUnorderedGridColumn},.375rem)`,
@@ -9872,16 +9866,16 @@ const getComponentCss$5 = () => {
                 ...addImportantToEachRule({
                     gridTemplateColumns: `var(${cssVariablePseudoSpace}) 1fr`,
                     columnGap: spacingStaticMedium,
-                    font: 'inherit',
-                    color: 'inherit',
+                    font: 'inherit', // ensures style can't be overwritten from outside
+                    color: 'inherit', // ensures style can't be overwritten from outside
                     ...hostHiddenStyles,
                 }),
             },
             ...addImportantToEachRule({
                 '::slotted(*)': {
-                    [cssVariableUnorderedGridColumn]: '.625rem',
-                    [cssVariableUnorderedPseudoContent]: '"–"',
-                    [cssVariableOrderedGridColumn]: '2rem',
+                    [cssVariableUnorderedGridColumn]: '.625rem', // reserves space for ::before (nested unordered list)
+                    [cssVariableUnorderedPseudoContent]: '"–"', // custom ::before char "–" (nested unordered list)
+                    [cssVariableOrderedGridColumn]: '2rem', // reserves space for ::before (nested ordered list)
                     [cssVariableOrderedPseudoSuffix]: '""', // don't show ::before suffix "." (nested ordered list)
                 },
                 '::slotted(*:last-child)': {
@@ -9937,7 +9931,7 @@ const getComponentCss$3 = (isDisabled, hideLabel, state, hasCounter, theme) => {
             ...mergeDeep(addImportantToEachRule(getSlottedTextFieldTextareaSelectStyles('textarea', state, false, theme, {
                 gridArea: '1/1',
                 // TODO: move into getSlottedTextFieldTextareaSelectStyles()
-                font: textSmallStyle.font,
+                font: textSmallStyle.font, // to override line-height
                 // TODO: move into getSlottedTextFieldTextareaSelectStyles()
                 padding: hasCounter
                     ? `12px ${formElementPaddingHorizontal} ${spacingStaticLarge}`
@@ -9945,8 +9939,8 @@ const getComponentCss$3 = (isDisabled, hideLabel, state, hasCounter, theme) => {
             })), {
                 // TODO: is it possible to move into getSlottedTextFieldTextareaSelectStyles()?
                 '::slotted(textarea)': {
-                    height: 'auto',
-                    minHeight: '200px',
+                    height: 'auto', // removes !important from getBaseChildStyles
+                    minHeight: '200px', // min-height should be overridable
                     resize: 'vertical', // overridable, too
                 },
             }),
@@ -10007,11 +10001,11 @@ const getComponentCss$1 = () => {
                 // In addition, a public css variable can be passed to overwrite the default position.
                 [cssVariablePositionBottomInternal]: `var(${cssVariablePositionBottom}, 56px)`,
                 bottom: `var(${cssVariablePositionBottomInternal})`,
-                maxWidth: '42rem',
                 zIndex: TOAST_Z_INDEX,
                 [getMediaQueryMin('s')]: {
                     left: '64px',
                     right: 'auto',
+                    maxWidth: 'min(42rem, calc(100vw - 64px * 2))',
                     [cssVariablePositionBottomInternal]: `var(${cssVariablePositionBottom}, 64px)`,
                     bottom: `var(${cssVariablePositionBottomInternal})`,
                 },
@@ -10041,7 +10035,7 @@ const getComponentCss = (size, theme) => {
                     outline: 0,
                     maxWidth: '100%',
                     maxHeight: '100%',
-                    boxSizing: 'content-box',
+                    boxSizing: 'content-box', // needed for correct height calculation when padding is set on host (e.g. custom click area)
                     ...(size !== 'inherit' && {
                         height: 'clamp(0.63rem, 0.42vw + 0.5rem, 1rem)',
                         // workaround for Safari to optimize image rendering