Add comments

packages/grafana-ui/src/components/ColorPicker/ColorPicker.tsx

@@ -9,7 +9,15 @@ import { SeriesColorPickerPopover } from './SeriesColorPickerPopover';
 import { withTheme } from '../../themes/ThemeContext';
 import { ColorPickerTrigger } from './ColorPickerTrigger';
 
+/**
+ * If you need custom trigger for the color picker you can do that with a render prop pattern and supply a function
+ * as a child. You will get show/hide function which you can map to desired interaction (like onClick or onMouseLeave)
+ * and a ref which needs to be passed to an HTMLElement for correct positioning. If you want to use class or functional
+ * component as a custom trigger you will need to forward the reference to first HTMLElement child.
+ */
 type ColorPickerTriggerRenderer = (props: {
+  // This should be a React.RefObject<HTMLElement> but due to how object refs are defined you cannot downcast from that
+  // to a specific type like React.RefObject<HTMLDivElement> even though it would be fine in runtime.
   ref: React.RefObject<any>;
   showColorPicker: () => void;
   hideColorPicker: () => void;
@@ -53,6 +61,9 @@ export const colorPickerFactory = <T extends ColorPickerProps>(
                 )}
 
                 {children ? (
+                  // Children have a bit weird type due to intersection used in the definition so we need to cast here,
+                  // but the definition is correct and should not allow to pass a children that does not conform to
+                  // ColorPickerTriggerRenderer type.
                   (children as ColorPickerTriggerRenderer)({
                     ref: this.pickerTriggerRef,
                     showColorPicker: showPopper,