Updating Gray-scale in colorMode()

src/color/setting.js

@@ -743,9 +743,9 @@ function setting(p5, fn){
    * Calling `colorMode(RGB, 100)` sets colors to use RGB color values
    * between 0 and 100. Pure red is `color(100, 0, 0)` in this model.
    *
-   * Calling `colorMode(HSB)` or `colorMode(HSL)` changes to HSB or HSL system
-   * instead of RGB. Pure red is `color(0, 100, 100)` in HSB and
-   * `color(0, 100, 50)` in HSL.
+   * Calling `colorMode(HSB)` or `colorMode(HSL)` changes to HSB or HSL systems instead of RGB.
+   * Pure red is `color(0, 100, 100)` in HSB and `color(0, 100, 50)` in HSL.
+   *
    * Some additional color modes that p5.js supports are:
    *
    * `RGBHDR` - High Dynamic Range RGB defined within the Display P3 color space.
@@ -758,7 +758,7 @@ function setting(p5, fn){
    *          of whiteness and blackness. This is the color model used by Chrome's GUI color picker.
    *          Pure red in HWB is represented as `color(0, 0, 0)` (i.e., hue 0 with 0% whiteness and 0% blackness).
    *    
-   *         <img src="assets/hwb.png"></img>
+   *          <img src="assets/hwb.png"></img>
    *
    * `LAB`    - Also known as CIE Lab, this color mode defines colors with Lightness, Alpha, and Beta.
    *          It is widely used in professional color measurement contexts due to its perceptual uniformity.
@@ -773,14 +773,33 @@ function setting(p5, fn){
    *
    * `OKLCH`  - An easier-to-use representation of OKLAB, expressing colors in terms of Lightness, Chroma, and Hue.
    *          This mode retains the perceptual benefits of OKLAB while offering a more intuitive format for color manipulation.
-   * 
+   *
    * <a href="#/p5.Color">p5.Color</a> objects remember the mode that they were
    * created in. Changing modes doesn't affect their appearance.
    *
+   *  `Single-value (Grayscale) Colors`:    
+   *  When a color is specified with only one parameter (e.g., `color(g)`), p5.js will interpret it
+   *  as a grayscale color. However, how that single parameter translates into a grayscale value
+   *  depends on the color mode:
+   *
+   * - `RGB, HSB, and HSL`: In RGB, the single value is interpreted using the “blue” maximum 
+   *   (i.e., the single parameter is mapped to the blue channel's max). 
+   *   In HSB and HSL, the single value is mapped to Brightness and Lightness max respectively with hue=0 . 
+   *   and saturation=0.
+   *
+   * - `LAB, LCH, OKLAB, and OKLCH`: The single value is taken to be the `lightness (L)` component,
+   *   with the specified max range for that channel.
+   *
+   * - `HWB`: Grayscale relies on both the` whiteness (W)` and `blackness (B)` channels. Since
+   *   a single value cannot directly account for two distinct channels, the library uses an
+   *   average of their max values to interpret the single grayscale parameter. For instance,
+   *   if W has a max of 50 and B has a max of 100, then the single grayscale parameter
+   *   is mapped using (50 + 100) / 2 = 75 as its effective maximum. More complex or negative
+   *   ranges are currently not handled, so results in those cases may be ambiguous.
+   *
    * @method colorMode
-   * @param {RGB|HSB|HSL|RGBHDR|HWB|LAB|LCH|OKLAB|OKLCH} mode   either RGB, HSB 
-   *                          or HSL, corresponding to Red/Green/Blue and 
-   *                          Hue/Saturation/Brightness (or Lightness).
+   * @param {RGB|HSB|HSL|RGBHDR|HWB|LAB|LCH|OKLAB|OKLCH} mode   either RGB, HSB, HSL,
+   *          or one of the extended modes described above.
    * @param {Number}  [max]  range for all values.
    * @chainable
    *
@@ -1092,7 +1111,55 @@ function setting(p5, fn){
    * }
    * </code>
    * </div>
+   * 
+   * @example
+   * <div>
+   * <code>
+   * 
+   *  // Example: Single-value (Grayscale) colors in different color modes. 
+   *  // Each rectangle is filled with one parameter, but its final color depends
+   *  // on how that parameter is interpreted by the current color mode.
+   *  
+   * 
+   * function setup() {
+   *   createCanvas(300, 200);
+   *   noStroke();
+   *   noLoop();
+   * }
+   * 
+   * function draw() {
+   *   //--- Left rectangle: RGB mode
+   *   colorMode(RGB, 255);
+   *   fill(128); // Interpreted as R=G=B=128 in RGB
+   *   rect(0, 0, 100, 200);
+   * 
+   *   //--- Middle rectangle: LAB mode
+   *   // In LAB, a single value is interpreted as Lightness (L).
+   *   // The default max for each LAB component is 100, so a single value of 50
+   *   // becomes roughly halfway in terms of lightness.
+   *   colorMode(LAB, 100);
+   *   fill(50); 
+   *   rect(100, 0, 100, 200);
+   * 
+   *   //--- Right rectangle: HWB mode
+   *   // In HWB, a single value is mapped onto whiteness and blackness together.
+   *   // Because both W and B are needed to specify a gray, the library averages
+   *   // their max values to interpret this single parameter. 
+   *   colorMode(HWB, 100);
+   *   fill(50);
+   *   rect(200, 0, 100, 200);
+   * 
+   *   // Add text labels
+   *   fill(0); // Switch to black text for clarity (RGB mode for text)
+   *   textSize(14);
+   *   text("RGB (128)", 10, 20);
+   *   text("LAB (50)", 105, 20);
+   *   text("HWB (50)", 205, 20);
+   * }
+   * </code>
+   * </div>
    */
+
   /**
    * @method colorMode
    * @param {RGB|HSB|HSL|RGBHDR|HWB|LAB|LCH|OKLAB|OKLCH} mode