fix(ui-color-picker): fix popover scrolling and button alignment issues

- Calculate popover max height dynamically to enable scrolling when
  content exceeds available viewport space
- Fix mixer button alignment visual jump on load by deferring
  measurement until CSS-in-JS styles are applied
- Use double requestAnimationFrame to ensure measurements happen after
  child components mount and styles are injected
- Add opacity transition to prevent visual jump when popover opens
- Reset calculated height state when popover closes

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: balzss

packages/ui-color-picker/src/ColorPicker/index.tsx

@@ -110,7 +110,9 @@ class ColorPicker extends Component<ColorPickerProps, ColorPickerState> {
       showHelperErrorMessages: false,
       openColorPicker: false,
       mixedColor: '',
-      labelHeight: 0
+      labelHeight: 0,
+      calculatedPopoverMaxHeight: undefined,
+      isHeightCalculated: false
     }
   }
 
@@ -130,7 +132,19 @@ class ColorPicker extends Component<ColorPickerProps, ColorPickerState> {
 
   handleInputContainerRef = (el: Element | null) => {
     this.inputContainerRef = el
-    this.setLabelHeight()
+
+    if (el) {
+      // Defer measurement until after layout is complete and CSS-in-JS styles are applied
+      requestAnimationFrame(() => {
+        this.setLabelHeight()
+      })
+    }
+  }
+
+  popoverContentRef: HTMLDivElement | null = null
+
+  handlePopoverContentRef = (el: HTMLDivElement | null) => {
+    this.popoverContentRef = el
   }
 
   setLabelHeight = () => {
@@ -143,6 +157,62 @@ class ColorPicker extends Component<ColorPickerProps, ColorPickerState> {
     }
   }
 
+  // Calculate the maximum height the popover can have without extending beyond
+  // the viewport. This enables scrolling when the ColorPicker's content (all
+  // color mixing controls, presets, and contrast checker) would otherwise exceed
+  // the available viewport space. Without this calculation, the popover would
+  // render off-screen on smaller viewports.
+  handlePopoverPositioned = (position?: { placement?: string }) => {
+    if (this.popoverContentRef) {
+      // Double requestAnimationFrame ensures measurements happen after all child components
+      // (ColorMixer, ColorPreset, ColorContrast) complete their mount lifecycle and Emotion
+      // finishes injecting CSS-in-JS styles. A single rAF was insufficient as styles are
+      // injected dynamically in componentDidMount(). This timing issue only manifested when
+      // StrictMode was disabled, since StrictMode's double-rendering provided an accidental
+      // second measurement pass.
+      requestAnimationFrame(() => {
+        // First frame: DOM structure is laid out
+        requestAnimationFrame(() => {
+          // Second frame: styles injected, child components mounted, dimensions stable
+          if (!this.popoverContentRef) return
+
+          const rect = this.popoverContentRef.getBoundingClientRect()
+          const viewportHeight = window.innerHeight
+
+          // Detect if popover is positioned above (top) or below (bottom) the trigger.
+          // The Position component provides placement strings like "top center" or "bottom center".
+          const placement = position?.placement || ''
+          const isPositionedAbove = placement.startsWith('top')
+
+          let availableHeight: number
+
+          if (isPositionedAbove) {
+            // When opening upward: available space is from viewport top to popover bottom.
+            // This is the space where the popover can expand within the viewport.
+            availableHeight = rect.top + rect.height - 16
+          } else {
+            // When opening downward: available space is from popover top to viewport bottom.
+            // Subtract a small buffer (16px) for padding/margin.
+            availableHeight = viewportHeight - rect.top - 16
+          }
+
+          const propMaxHeight = this.props.popoverMaxHeight
+          let calculatedMaxHeight = `${Math.max(100, availableHeight)}px`
+
+          // If prop specifies a maxHeight, respect it as an additional constraint
+          if (propMaxHeight && propMaxHeight !== '100vh') {
+            calculatedMaxHeight = propMaxHeight
+          }
+
+          this.setState({
+            calculatedPopoverMaxHeight: calculatedMaxHeight,
+            isHeightCalculated: true
+          })
+        })
+      })
+    }
+  }
+
   componentDidMount() {
     this.props.makeStyles?.({ ...this.state, isSimple: this.isSimple })
     this.checkSettings()
@@ -427,7 +497,12 @@ class ColorPicker extends Component<ColorPickerProps, ColorPickerState> {
       }
       isShowingContent={this.state.openColorPicker}
       onShowContent={() => {
-        this.setState({ openColorPicker: true, mixedColor: this.state.hexCode })
+        this.setState({
+          openColorPicker: true,
+          mixedColor: this.state.hexCode,
+          calculatedPopoverMaxHeight: undefined,
+          isHeightCalculated: false
+        })
       }}
       onHideContent={() => {
         this.setState({ openColorPicker: false })
@@ -438,8 +513,13 @@ class ColorPicker extends Component<ColorPickerProps, ColorPickerState> {
       shouldReturnFocus
       shouldCloseOnDocumentClick
       offsetY="10rem"
+      onPositioned={this.handlePopoverPositioned}
+      onPositionChanged={this.handlePopoverPositioned}
     >
-      <div css={this.props.styles?.popoverContentContainer}>
+      <div
+        css={this.props.styles?.popoverContentContainer}
+        ref={this.handlePopoverContentRef}
+      >
         {this.isDefaultPopover
           ? this.renderDefaultPopoverContent()
           : this.renderCustomPopoverContent()}
@@ -470,7 +550,9 @@ class ColorPicker extends Component<ColorPickerProps, ColorPickerState> {
             () =>
               this.setState({
                 openColorPicker: false,
-                mixedColor: this.state.hexCode
+                mixedColor: this.state.hexCode,
+                calculatedPopoverMaxHeight: undefined,
+                isHeightCalculated: false
               })
           )}
       </div>
@@ -576,7 +658,9 @@ class ColorPicker extends Component<ColorPickerProps, ColorPickerState> {
           onClick={() =>
             this.setState({
               openColorPicker: false,
-              mixedColor: this.state.hexCode
+              mixedColor: this.state.hexCode,
+              calculatedPopoverMaxHeight: undefined,
+              isHeightCalculated: false
             })
           }
           color="secondary"
@@ -639,7 +723,10 @@ class ColorPicker extends Component<ColorPickerProps, ColorPickerState> {
         {!this.isSimple && (
           <div
             css={this.props.styles?.colorMixerButtonContainer}
-            style={{ paddingTop: this.state.labelHeight }}
+            style={{
+              alignSelf: this.state.labelHeight > 0 ? 'flex-start' : 'flex-end',
+              paddingTop: this.state.labelHeight
+            }}
           >
             <div css={this.props.styles?.colorMixerButtonWrapper}>
               {this.renderPopover()}

packages/ui-color-picker/src/ColorPicker/props.ts

@@ -247,6 +247,8 @@ type ColorPickerState = {
   openColorPicker: boolean
   mixedColor: string
   labelHeight: number
+  calculatedPopoverMaxHeight: string | undefined
+  isHeightCalculated: boolean
 }
 
 type PropKeys = keyof ColorPickerOwnProps

packages/ui-color-picker/src/ColorPicker/styles.ts

@@ -54,7 +54,7 @@ const generateStyle = (
     spacing
   } = componentTheme
   const { checkContrast, popoverMaxHeight, margin } = props
-  const { isSimple } = state
+  const { isSimple, calculatedPopoverMaxHeight } = state
 
   const cssMargin = mapSpacingToShorthand(margin, spacing)
   return {
@@ -127,8 +127,14 @@ const generateStyle = (
     },
     popoverContentContainer: {
       label: 'colorPicker__popoverContentContainer',
-      maxHeight: popoverMaxHeight || '100vh',
-      overflow: 'auto'
+      maxHeight: calculatedPopoverMaxHeight || popoverMaxHeight || '100vh',
+      overflowY: 'auto',
+      overflowX: 'hidden',
+      scrollbarGutter: 'stable',
+      display: 'flex',
+      flexDirection: 'column',
+      opacity: state.isHeightCalculated ? 1 : 0,
+      transition: 'opacity 150ms ease-in'
     },
     colorMixerButtonWrapper: {
       label: 'colorPicker__colorMixerButtonWrapper',