Add more documentation around ColorSwatchButton and colorToHex

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. <br /><br />_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:<br />• `swatchColors`: Array of colors to show as preset buttons.<br />• `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).<br />• `disableAlpha`: If true, disables the alpha/transparency slider.<br />• `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
 

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

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

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