diff --git a/README.md b/README.md
index 61d00c6..d008a51 100644
--- a/README.md
+++ b/README.md
@@ -258,6 +258,7 @@ Namely, this version of the extension, coupled with the `mui-tiptap` CSS styles
| `TableBubbleMenu` | Renders a bubble menu to manipulate the contents of a Table (add or delete columns or rows, merge cells, etc.), when the user's caret/selection is inside a Table. For use with [mui-tiptap’s `TableImproved` extension](#tableimproved) or Tiptap’s `@tiptap/extension-table` extension.
_If you're using `RichTextEditor`, include this component via `RichTextEditor`’s `children` render-prop. Otherwise, include the `TableBubbleMenu` as a child of the component where you call `useEditor` and render your `RichTextField` or `RichTextContent`. (The bubble menu itself will be positioned appropriately as long as it is re-rendered whenever the Tiptap `editor` forces an update, which will happen if it's a child of the component using `useEditor`). See [`src/demo/Editor.tsx`](./src/demo/Editor.tsx) for an example of this._ |
| `ControlledBubbleMenu` | General-purpose component for building your own custom bubble menus, [solving some shortcomings](https://github.com/ueberdosis/tiptap/issues/2305#issuecomment-1020665146) of [Tiptap’s `BubbleMenu`](https://tiptap.dev/api/extensions/bubble-menu). This is what both `LinkBubbleMenu` and `TableBubbleMenu` use under the hood. |
| `ColorPicker` | A color-picker that includes hue/saturation/alpha gradient selectors (via [react-colorful](https://github.com/omgovich/react-colorful)), plus a text input to enter a color directly, and optional `swatchColors` for color presets. Used by `MenuButtonColorPicker`/`MenuButtonTextColor`/`MenuButtonHighlightColor` under the hood. Important props:
• `swatchColors`: Array of colors to show as preset buttons.
• `colorToHex`: Override the default implementation for converting a given CSS color string to a string in hex format (e.g. `"#ff0000"`). Should return null if the given color cannot be parsed as valid. See `ColorPickerProps` definition for more details, such as examples using more full-featured libraries like [colord](https://www.npmjs.com/package/colord) or [tinycolor2](https://www.npmjs.com/package/@ctrl/tinycolor).
• `disableAlpha`: If true, disables the alpha/transparency slider.
• `value`/`onChange`: controlled color value string (empty string if unset) and its change callback. |
+| `ColorSwatchButton` | Renders a button that shows and allows selecting a color preset. Utilized by `ColorPicker` for its `swatchColors`. |
#### Controls components
diff --git a/src/controls/ColorPicker.tsx b/src/controls/ColorPicker.tsx
index 4fa7ba9..e697302 100644
--- a/src/controls/ColorPicker.tsx
+++ b/src/controls/ColorPicker.tsx
@@ -43,6 +43,15 @@ export type ColorPickerProps = {
* to a string in hex format (e.g. "#ff0000"). Should return null if the given
* color cannot be parsed as valid.
*
+ * Needed to ensure that the hue/saturation/alpha color picker can interpret
+ * the given color `value` (regardless of its format), and also used to
+ * parse/handle the user's text input.
+ *
+ * Examples:
+ * "rgb(169, 79, 211)" -> "#a94fd3"
+ * "#a94fd3" -> "#a94fd3"
+ * "not a color" -> null
+ *
* By default uses a wrapped version of @mui/material's `rgbToHex` function,
* which supports input strings in these formats: hex like #000 and #00000000,
* rgb(), rgba(), hsl(), hsla(), and color(). See
diff --git a/src/controls/ColorSwatchButton.tsx b/src/controls/ColorSwatchButton.tsx
index aa7c495..5aa62ab 100644
--- a/src/controls/ColorSwatchButton.tsx
+++ b/src/controls/ColorSwatchButton.tsx
@@ -24,6 +24,10 @@ export interface ColorSwatchButtonProps
padding?: string | number;
}
+/**
+ * Renders a button in the given color `value`, useful for showing and allowing
+ * selecting a color preset.
+ */
export const ColorSwatchButton = forwardRef<
ElementRef<"button">,
ColorSwatchButtonProps
diff --git a/src/utils/color.ts b/src/utils/color.ts
index 08ec021..bafc80c 100644
--- a/src/utils/color.ts
+++ b/src/utils/color.ts
@@ -4,6 +4,16 @@ import { rgbToHex } from "@mui/material";
* Convert a color string to a color in hex string format (e.g. "#ff0000"), or
* return null if the given string cannot be parsed as a valid color.
*
+ * Examples:
+ * "rgb(169, 79, 211)" -> "#a94fd3"
+ * "#a94fd3" -> "#a94fd3"
+ * "not a color" -> null
+ *
+ * Uses @mui/material's `rgbToHex` function, which supports input strings in
+ * these formats: hex like #000 and #00000000, rgb(), rgba(), hsl(), hsla(), and
+ * color(). See
+ * https://github.com/mui/material-ui/blob/e00a4d857fb2ea1b181afc35d0fd1ffc5631f0fe/packages/mui-system/src/colorManipulator.js#L54
+ *
* Separate third party libraries could be used instead of this function to
* offer more full-featured parsing (e.g. handling CSS color name keywords,
* cmyk, etc.), such as colord (https://www.npmjs.com/package/colord) and