Differentiate between global and game-specific contexts and palettes; add 'custom' colour function and buttons to the playground

Author: Perlkonig

src/index.ts

@@ -245,7 +245,7 @@ export const render = (json: APRenderRep, opts = {} as IRenderOptions): Svg => {
     if ( (renderer === undefined) || (renderer === null) ) {
         throw new Error(`Could not find the renderer "${ json.renderer }".`);
     }
-    renderer.render(json, draw, {sheets: opts.sheets, patterns: opts.patterns, patternList: opts.patternList, colourBlind: opts.colourBlind, colours: opts.colours, colourContext: opts.colourContext, rotate: opts.rotate, showAnnotations: opts.showAnnotations, boardClick, boardHover, glyphmap: opts.glyphmap});
+    renderer.render(json, draw, {sheets: opts.sheets, patterns: opts.patterns, patternList: opts.patternList, colourBlind: opts.colourBlind, colours: opts.colours, coloursGlobal: opts.coloursGlobal, colourContext: opts.colourContext, contextGlobal: opts.contextGlobal, rotate: opts.rotate, showAnnotations: opts.showAnnotations, boardClick, boardHover, glyphmap: opts.glyphmap,});
     if (draw.bbox().h !== 0
         && draw.viewbox().h === 0  // Only set it here if the renderer didn't set it
         ) {

src/renderers/_base.ts

@@ -45,12 +45,24 @@ export interface IRendererOptionsIn {
      * turns it into an IColourContext object.
      */
     colourContext?: {[k: string]: string};
+    /**
+     * I want to know whether the custom context being passed is a global preference or
+     * a game-specific one. The idea being that the colourFunc `custom` should prefer
+     * the developer defaults over global customizations, but defer to game-specific ones.
+     */
+    contextGlobal: boolean;
     /**
      * A list of hexadecimal colour strings to be used as player colours. Be sure to provide enough for the number of players defined.
      * Defaults to a set of nine colours, defined in the constructor.
      *
      */
     colours?: string[];
+    /**
+     * I want to know whether the custom colours being passed are a global preference or
+     * a game-specific one. The idea being that the colourFunc `custom` should prefer
+     * the developer defaults over global customizations, but defer to game-specific ones.
+     */
+    coloursGlobal: boolean;
     /**
      * Signals whether you want black and white patterns used instead of colours.
      *
@@ -113,7 +125,9 @@ export interface IRendererOptionsIn {
 export interface IRendererOptionsOut {
     sheets: string[];
     colourContext: IColourContext;
+    contextGlobal: boolean;
     colours: string[];
+    coloursGlobal: boolean;
     patterns: boolean;
     patternList: string[];
     colourBlind: boolean;
@@ -221,8 +235,10 @@ export abstract class RendererBase {
                 annotations: "#000",
                 labels: "#000",
             },
+            contextGlobal: true,
             colourBlind: false,
             colours: [],
+            coloursGlobal: true,
             patterns: false,
             patternList: ["microbial", "chevrons", "honeycomb", "triangles", "wavy", "slant", "dots", "starsWhite", "cross", "houndstooth"],
             showAnnotations: true,
@@ -315,6 +331,7 @@ export abstract class RendererBase {
                     this.options.colourContext[label] = color.toHexString();
                 }
             }
+            this.options.contextGlobal = opts.contextGlobal ?? true;
         }
 
         // Validate colour list if given
@@ -328,6 +345,7 @@ export abstract class RendererBase {
                 normalized.push(color.toHexString());
             }
             this.options.colours = [...normalized];
+            this.options.coloursGlobal = opts.coloursGlobal ?? true;
         }
 
         // Check for annotation screening
@@ -3940,7 +3958,49 @@ export abstract class RendererBase {
                 else if (val.func === "bestContrast") {
                     const bg = this.resolveColour(val.bg) as string;
                     const fg = val.fg.map(c => this.resolveColour(c) as string);
-                    return tinycolor.mostReadable(bg, fg).toHexString();
+                    colour = tinycolor.mostReadable(bg, fg).toHexString();
+                }
+                else if (val.func === "custom") {
+                    // if `palette` is a number
+                    if (typeof val.palette === "number") {
+                        // only choose if passed colours are game-specific customizations
+                        if (!this.options.coloursGlobal) {
+                            colour = this.resolveColour(val.palette) as string;
+                        } else {
+                            colour = this.resolveColour(val.default) as string;
+                        }
+                    }
+                    // if `palette` is a context
+                    else if (typeof val.palette === "string" && val.palette.startsWith("_context_")) {
+                        // only choose if passed context is game-specific customization
+                        if (!this.options.contextGlobal) {
+                            colour = this.resolveColour(val.palette) as string;
+                        } else {
+                            colour = this.resolveColour(val.default) as string;
+                        }
+                    }
+                    // otherwise, rely on `paletteType`
+                    else if ("paletteType" in val && val.paletteType !== undefined) {
+                        if (val.paletteType === "context") {
+                            // only choose if passed context is game-specific customization
+                            if (!this.options.contextGlobal) {
+                                colour = this.resolveColour(val.palette) as string;
+                            } else {
+                                colour = this.resolveColour(val.default) as string;
+                            }
+                        } else {
+                            // only choose if passed colours are game-specific customizations
+                            if (!this.options.coloursGlobal) {
+                                colour = this.resolveColour(val.palette) as string;
+                            } else {
+                                colour = this.resolveColour(val.default) as string;
+                            }
+                        }
+                    }
+                    // otherwise throw
+                    else {
+                        throw new Error(`Could not resolve the custom function. If "palette" is neither a number nor a context, then "paletteType" is required.`);
+                    }
                 }
             }
         } else if (typeof val === "number") {

src/schemas/schema.d.ts

@@ -12,7 +12,7 @@ export type Colourstrings = string;
 /**
  * Colours can also be derived using various functions.
  */
-export type Colourfuncs = FunctionFlatten | FunctionBestContrast | FunctionLighten;
+export type Colourfuncs = FunctionFlatten | FunctionBestContrast | FunctionLighten | FunctionCustom;
 export type PositiveInteger = number;
 /**
  * Schema for the `matrix` part of a polyomino-related feature
@@ -386,6 +386,18 @@ export interface FunctionLighten {
   ds: number;
   dl: number;
 }
+/**
+ * Supports game developers choosing nonstandard default colours while still allowing players to customize. Ties a default value to a player number or context value, and the function chooses which to use based on whether the user passed in custom values.
+ */
+export interface FunctionCustom {
+  func: "custom";
+  default: PositiveInteger | Colourstrings | Colourfuncs;
+  palette: PositiveInteger | Colourstrings | Colourfuncs;
+  /**
+   * Only needed if the `palette` value is a function and so the function can't tell what test to use.
+   */
+  paletteType?: "player" | "context";
+}
 /**
  * A gradient one can use for flood fills and the like.
  */

src/schemas/schema.json

@@ -117,12 +117,42 @@
             "required": ["func", "bg", "fg"],
             "additionalProperties": false
         },
+        "functionCustom": {
+            "description": "Supports game developers choosing nonstandard default colours while still allowing players to customize. Ties a default value to a player number or context value, and the function chooses which to use based on whether the user passed in custom values.",
+            "type": "object",
+            "properties": {
+                "func": {
+                    "enum": ["custom"]
+                },
+                "default": {
+                    "anyOf": [
+                        {"$ref": "#/$defs/positiveInteger"},
+                        {"$ref": "#/$defs/colourstrings"},
+                        {"$ref": "#/$defs/colourfuncs"}
+                    ]
+                },
+                "palette": {
+                    "anyOf": [
+                        {"$ref": "#/$defs/positiveInteger"},
+                        {"$ref": "#/$defs/colourstrings"},
+                        {"$ref": "#/$defs/colourfuncs"}
+                    ]
+                },
+                "paletteType": {
+                    "description": "Only needed if the `palette` value is a function and so the function can't tell what test to use.",
+                    "enum": ["player", "context"]
+                }
+            },
+            "required": ["func", "default", "palette"],
+            "additionalProperties": false
+        },
        "colourfuncs": {
             "description": "Colours can also be derived using various functions.",
             "anyOf": [
                 {"$ref": "#/$defs/functionFlatten"},
                 {"$ref": "#/$defs/functionBestContrast"},
-                {"$ref": "#/$defs/functionLighten"}
+                {"$ref": "#/$defs/functionLighten"},
+                {"$ref": "#/$defs/functionCustom"}
             ]
         },
         "rowCol": {

test/playground.html

@@ -26,6 +26,10 @@
                 } else if (radio === "patterns") {
                     options.patterns = true;
                 }
+                if (document.getElementById("chkColoursGlobal").checked) {
+                    options.colours = ["#e31a1c","#1f78b4","#33a02c","#ffff99","#6a3d9a","#ff7f00","#b15928","#fb9a99","#a6cee3","#b2df8a","#fdbf6f","#cab2d6"]
+                    options.coloursGlobal = false;
+                }
                 let rotation = 0;
                 const freestyle = parseInt(document.getElementById("rotFree").value, 10);
                 if (freestyle === 0) {
@@ -51,6 +55,9 @@
                     labels: labels.value,
                     annotations: notes.value,
                 };
+                if (document.getElementById("chkContextGlobal").checked) {
+                    options.contextGlobal = false;
+                }
                 var div = document.getElementById("drawing");
                 div.style.backgroundColor = bg.value;
 
@@ -596,6 +603,10 @@ <h1>JSON Input</h1>
                     <input type="radio" id="fillPatterns" name="playerfill" value="patterns">
                     <label for="fillPatterns">Black-and-white patterns (10 max)</label>
                 </div>
+                <div>
+                    <input type="checkbox" id="chkColoursGlobal">
+                    <label for="chkColoursGlobal">Game-specific customization</label>
+                </div>
                 <hr>
                 <div>
                     <label for="ccBackground">Background</label>
@@ -616,6 +627,9 @@ <h1>JSON Input</h1>
                 <div>
                     <button id="btnLight" type="button">Light Mode</button>
                     <button id="btnDark" type="button">Dark Mode</button>
+                    &emsp;
+                    <input type="checkbox" id="chkContextGlobal">
+                    <label for="chkContextGlobal">Game-specific customization</label>
                 </div>
                 <hr>
                 <div>