/*
 * Smart GWT (GWT for SmartClient)
 * Copyright 2008 and beyond, Isomorphic Software, Inc.
 *
 * Smart GWT is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License version 3
 * as published by the Free Software Foundation.  Smart GWT is also
 * available under typical commercial license terms - see
 * http://smartclient.com/license
 *
 * This software is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * Lesser General Public License for more details.
 */
/* sgwtgen */
 
package com.smartgwt.client.util;


import com.smartgwt.client.event.*;
import com.smartgwt.client.core.*;
import com.smartgwt.client.types.*;
import com.smartgwt.client.data.*;
import com.smartgwt.client.data.Record;
import com.smartgwt.client.data.events.*;
import com.smartgwt.client.browser.window.*;
import com.smartgwt.client.rpc.*;
import com.smartgwt.client.ai.*;
import com.smartgwt.client.callbacks.*;
import com.smartgwt.client.tools.*;
import com.smartgwt.client.bean.*;
import com.smartgwt.client.widgets.*;
import com.smartgwt.client.widgets.ai.*;
import com.smartgwt.client.widgets.events.*;
import com.smartgwt.client.widgets.form.*;
import com.smartgwt.client.widgets.form.validator.*;
import com.smartgwt.client.widgets.form.fields.*;
import com.smartgwt.client.widgets.tile.*;
import com.smartgwt.client.widgets.tile.events.*;
import com.smartgwt.client.widgets.grid.*;
import com.smartgwt.client.widgets.grid.events.*;
import com.smartgwt.client.widgets.chart.*;
import com.smartgwt.client.widgets.layout.*;
import com.smartgwt.client.widgets.layout.events.*;
import com.smartgwt.client.widgets.menu.*;
import com.smartgwt.client.widgets.tour.*;
import com.smartgwt.client.widgets.notify.*;
import com.smartgwt.client.widgets.rte.*;
import com.smartgwt.client.widgets.rte.events.*;
import com.smartgwt.client.widgets.ace.*;
import com.smartgwt.client.widgets.ace.events.*;
import com.smartgwt.client.widgets.tab.*;
import com.smartgwt.client.widgets.toolbar.*;
import com.smartgwt.client.widgets.tree.*;
import com.smartgwt.client.widgets.tree.events.*;
import com.smartgwt.client.widgets.tableview.*;
import com.smartgwt.client.widgets.viewer.*;
import com.smartgwt.client.widgets.calendar.*;
import com.smartgwt.client.widgets.calendar.events.*;
import com.smartgwt.client.widgets.cube.*;
import com.smartgwt.client.widgets.notify.*;
import com.smartgwt.client.widgets.drawing.*;
import java.util.ArrayList;
import java.util.Date;
import java.util.HashMap;
import java.util.HashSet;
import java.util.Iterator;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.Set;

import com.google.gwt.event.shared.*;
import com.google.gwt.dom.client.Element;
import com.google.gwt.user.client.ui.Widget;
import com.google.gwt.core.client.JavaScriptObject;

import com.smartgwt.client.util.*;
import com.smartgwt.client.util.events.*;
import com.smartgwt.client.util.workflow.*;
import com.smartgwt.client.util.workflow.Process; // required to override java.lang.Process
import com.smartgwt.client.util.tour.*;


/**
 * Utility class for color format conversion, validation, and manipulation. Accepts any valid CSS color specification (hex,
 * rgb/rgba, hsl/hsla, oklch, named colors, "transparent") and converts between formats. See the {@link
 * com.smartgwt.client.docs.ColorOverview Color Overview} for a detailed guide to color spaces, formats, manipulation, CSS
 * color relationships, and palettes. <P> The core entry points are {@link com.smartgwt.client.util.Colors#getColor
 * getColor()} to parse any color into a {@link com.smartgwt.client.util.Color} object (with RGB, HSL, and oklch properties
 * pre-computed), {@link com.smartgwt.client.util.Colors#getString getString()} to convert back to a CSS string, and {@link
 * com.smartgwt.client.util.Colors#getValues getValues()} for raw numeric components in a single color space. {@link
 * com.smartgwt.client.util.Colors#adjust adjust()} is the general-purpose manipulation method - all convenience methods
 * like {@link com.smartgwt.client.util.Colors#lighten lighten()}, {@link com.smartgwt.client.util.Colors#saturate
 * saturate()}, etc. delegate to it. <P> See the {@link com.smartgwt.client.docs.ColorOverview Color Overview} for a full
 * guide organized by topic: {@link com.smartgwt.client.util.Colors#getColor conversion}, {@link
 * com.smartgwt.client.util.Colors#isDark inspection}, {@link com.smartgwt.client.util.Colors#adjust manipulation}
 * (including {@link com.smartgwt.client.util.Colors#flatten alpha compositing}), {@link
 * com.smartgwt.client.util.Colors#colorScale palettes} and {@link com.smartgwt.client.util.Colors#triad harmony}, {@link
 * com.smartgwt.client.util.Colors#palette theme generation}, and {@link com.smartgwt.client.util.Colors#resolveCSS CSS
 * color relationships}.
 */
@BeanFactory.FrameworkClass
public class Colors {


    // ********************* Static Attributes ***********************


    // ********************* Static Methods ***********************

	/**
     * The general-purpose method for deriving a related color from a base color. Accepts any combination of adjustment keys in
     * the <code>deltas</code> object and returns the result as a CSS color string. Single-axis convenience wrappers - {@link
     * com.smartgwt.client.util.Colors#lighten lighten()}, {@link com.smartgwt.client.util.Colors#darken darken()}, {@link
     * com.smartgwt.client.util.Colors#saturate saturate()}, {@link com.smartgwt.client.util.Colors#desaturate desaturate()},
     * and {@link com.smartgwt.client.util.Colors#complement complement()} - all delegate to this method. <P> <b>Friendly
     * percentage keys</b> (recommended for most uses): <ul> <li><b>lightness</b> (-100 to 100): positive values lighten
     * (toward white), negative darken     (toward black). See {@link com.smartgwt.client.util.Colors#lighten lighten()}/{@link
     * com.smartgwt.client.util.Colors#darken darken}. <li><b>saturation</b> (-100 to 100): positive values intensify color,
     * negative desaturate     toward gray. See {@link com.smartgwt.client.util.Colors#saturate saturate()}/{@link
     * com.smartgwt.client.util.Colors#desaturate desaturate}. <li><b>hue</b> (degrees): signed rotation around the color
     * wheel. See     {@link com.smartgwt.client.util.Colors#complement complement()} for the hue wheel reference.
     * <li><b>alpha</b>: signed delta to opacity (0 = transparent, 1 = opaque). </ul> <P> <b>RGB delta keys</b> (for direct
     * channel control): <ul> <li><b>red</b>: signed delta to the red channel (0-255). <li><b>green</b>: signed delta to the
     * green channel (0-255). <li><b>blue</b>: signed delta to the blue channel (0-255). </ul> RGB deltas are applied first (in
     * RGB space, clamped to 0-255), before any oklch adjustments. This allows combining RGB shifts with perceptual adjustments
     * in a single call, e.g. <code>{red: 20, lightness: 10}</code>. <P> <b>Raw oklch keys</b> (for fine-grained control - see
     * the <a href='https://oklch.com/' target='_blank'>oklch color space</a>): <ul> <li><b>L</b>: signed delta to lightness
     * (0-1). +0.1 is noticeably lighter. <li><b>C</b>: signed delta to chroma (0 = gray, max ~0.4). -0.05 desaturates subtly.
     * <li><b>h</b> and <b>alpha</b> work the same as the friendly keys above. </ul> All key groups may be mixed freely; RGB
     * deltas are applied first, then friendly percentage keys, then raw oklch keys. The output format defaults to the input
     * format, so <code>rgb(...)</code> input returns <code>rgb(...)</code> output, etc. <P> Examples:
     * @param color base color - any valid CSS color string or structured object     from {@link com.smartgwt.client.util.Colors#getColor
     * getColor()}
     * @param deltas adjustment keys - any combination of RGB keys (<code>red</code>,     <code>green</code>, <code>blue</code>), friendly
     * keys (<code>lightness</code>,     <code>saturation</code>, <code>hue</code>, <code>alpha</code>), and/or raw oklch keys 
     *    (<code>L</code>, <code>C</code>, <code>h</code>). See the key lists above.
     *
     * @return CSS color string in the requested format, or null if the input is not a     valid color
     * @see com.smartgwt.client.util.Colors#lighten
     * @see com.smartgwt.client.util.Colors#darken
     * @see com.smartgwt.client.util.Colors#saturate
     * @see com.smartgwt.client.util.Colors#desaturate
     * @see com.smartgwt.client.util.Colors#complement
     */
    public static native String adjust(String color, Map deltas) /*-{
        var ret = $wnd.isc.Colors.adjust(color, deltas == null ? null : @com.smartgwt.client.util.JSOHelper::convertMapToJavascriptObject(Ljava/util/Map;)(deltas));
        return ret;
    }-*/;

	/**
     * The general-purpose method for deriving a related color from a base color. Accepts any combination of adjustment keys in
     * the <code>deltas</code> object and returns the result as a CSS color string. Single-axis convenience wrappers - {@link
     * com.smartgwt.client.util.Colors#lighten lighten()}, {@link com.smartgwt.client.util.Colors#darken darken()}, {@link
     * com.smartgwt.client.util.Colors#saturate saturate()}, {@link com.smartgwt.client.util.Colors#desaturate desaturate()},
     * and {@link com.smartgwt.client.util.Colors#complement complement()} - all delegate to this method. <P> <b>Friendly
     * percentage keys</b> (recommended for most uses): <ul> <li><b>lightness</b> (-100 to 100): positive values lighten
     * (toward white), negative darken     (toward black). See {@link com.smartgwt.client.util.Colors#lighten lighten()}/{@link
     * com.smartgwt.client.util.Colors#darken darken}. <li><b>saturation</b> (-100 to 100): positive values intensify color,
     * negative desaturate     toward gray. See {@link com.smartgwt.client.util.Colors#saturate saturate()}/{@link
     * com.smartgwt.client.util.Colors#desaturate desaturate}. <li><b>hue</b> (degrees): signed rotation around the color
     * wheel. See     {@link com.smartgwt.client.util.Colors#complement complement()} for the hue wheel reference.
     * <li><b>alpha</b>: signed delta to opacity (0 = transparent, 1 = opaque). </ul> <P> <b>RGB delta keys</b> (for direct
     * channel control): <ul> <li><b>red</b>: signed delta to the red channel (0-255). <li><b>green</b>: signed delta to the
     * green channel (0-255). <li><b>blue</b>: signed delta to the blue channel (0-255). </ul> RGB deltas are applied first (in
     * RGB space, clamped to 0-255), before any oklch adjustments. This allows combining RGB shifts with perceptual adjustments
     * in a single call, e.g. <code>{red: 20, lightness: 10}</code>. <P> <b>Raw oklch keys</b> (for fine-grained control - see
     * the <a href='https://oklch.com/' target='_blank'>oklch color space</a>): <ul> <li><b>L</b>: signed delta to lightness
     * (0-1). +0.1 is noticeably lighter. <li><b>C</b>: signed delta to chroma (0 = gray, max ~0.4). -0.05 desaturates subtly.
     * <li><b>h</b> and <b>alpha</b> work the same as the friendly keys above. </ul> All key groups may be mixed freely; RGB
     * deltas are applied first, then friendly percentage keys, then raw oklch keys. The output format defaults to the input
     * format, so <code>rgb(...)</code> input returns <code>rgb(...)</code> output, etc. <P> Examples:
     * @param color base color - any valid CSS color string or structured object     from {@link com.smartgwt.client.util.Colors#getColor
     * getColor()}
     * @param deltas adjustment keys - any combination of RGB keys (<code>red</code>,     <code>green</code>, <code>blue</code>), friendly
     * keys (<code>lightness</code>,     <code>saturation</code>, <code>hue</code>, <code>alpha</code>), and/or raw oklch keys 
     *    (<code>L</code>, <code>C</code>, <code>h</code>). See the key lists above.
     * @param outputFormat format for the returned string; defaults to the detected     format of the input color (hex for named colors)
     *
     * @return CSS color string in the requested format, or null if the input is not a     valid color
     * @see com.smartgwt.client.util.Colors#lighten
     * @see com.smartgwt.client.util.Colors#darken
     * @see com.smartgwt.client.util.Colors#saturate
     * @see com.smartgwt.client.util.Colors#desaturate
     * @see com.smartgwt.client.util.Colors#complement
     */
    public static native String adjust(String color, Map deltas, ColorFormat outputFormat) /*-{
        var ret = $wnd.isc.Colors.adjust(color, deltas == null ? null : @com.smartgwt.client.util.JSOHelper::convertMapToJavascriptObject(Ljava/util/Map;)(deltas), outputFormat == null ? null : outputFormat.@com.smartgwt.client.types.ColorFormat::getValue()());
        return ret;
    }-*/;
	

	/**
     * Returns a set of analogous colors - hues near the original, evenly spaced within a segment of the color wheel. Defaults
     * to 6 results spanning 30 degrees.
     * @param color base color
     *
     * @return CSS color strings
     */
    public static native String[] analogous(String color) /*-{
        var ret = $wnd.isc.Colors.analogous(color);
        if(ret == null) return null;
        return @com.smartgwt.client.util.ConvertTo::arrayOfString(Lcom/google/gwt/core/client/JavaScriptObject;)(ret);
    }-*/;

	/**
     * Returns a set of analogous colors - hues near the original, evenly spaced within a segment of the color wheel. Defaults
     * to 6 results spanning 30 degrees.
     * @param color base color
     *
     * @return CSS color strings
     */
    public static native String[] analogous(Color color) /*-{
        var ret = $wnd.isc.Colors.analogous(color.@com.smartgwt.client.core.DataClass::getJsObj()());
        if(ret == null) return null;
        return @com.smartgwt.client.util.ConvertTo::arrayOfString(Lcom/google/gwt/core/client/JavaScriptObject;)(ret);
    }-*/;

    /**
     * See {@link Colors#analogous(java.lang.String, int, int, com.smartgwt.client.types.ColorFormat) analogous()}
     */
    public static String[] analogous(String color, int results){
        return analogous(color, results, (Integer) null, null);
    }

    /**
     * See {@link Colors#analogous(com.smartgwt.client.util.Color, int, int, com.smartgwt.client.types.ColorFormat) analogous()}
     */
    public static String[] analogous(Color color, int results){
        return analogous(color, results, (Integer) null, null);
    }
    /**
     * See {@link Colors#analogous(java.lang.String, int, int, com.smartgwt.client.types.ColorFormat) analogous()}
     */
    public static String[] analogous(String color, int results, int slices){
        return analogous(color, results, slices, null);
    }

    /**
     * See {@link Colors#analogous(com.smartgwt.client.util.Color, int, int, com.smartgwt.client.types.ColorFormat) analogous()}
     */
    public static String[] analogous(Color color, int results, int slices){
        return analogous(color, results, slices, null);
    }
	/**
     * Returns a set of analogous colors - hues near the original, evenly spaced within a segment of the color wheel. Defaults
     * to 6 results spanning 30 degrees.
     * @param color base color
     * @param results number of colors to return (default 6)
     * @param slices how many slices to divide the wheel into (default 30, meaning each     step is 12 degrees)
     * @param outputFormat output format; defaults to input format
     *
     * @return CSS color strings
     */
    public static native String[] analogous(String color, int results, int slices, ColorFormat outputFormat) /*-{
        var ret = $wnd.isc.Colors.analogous(color, results, slices, outputFormat == null ? null : outputFormat.@com.smartgwt.client.types.ColorFormat::getValue()());
        if(ret == null) return null;
        return @com.smartgwt.client.util.ConvertTo::arrayOfString(Lcom/google/gwt/core/client/JavaScriptObject;)(ret);
    }-*/;

	/**
     * Returns a set of analogous colors - hues near the original, evenly spaced within a segment of the color wheel. Defaults
     * to 6 results spanning 30 degrees.
     * @param color base color
     * @param results number of colors to return (default 6)
     * @param slices how many slices to divide the wheel into (default 30, meaning each     step is 12 degrees)
     * @param outputFormat output format; defaults to input format
     *
     * @return CSS color strings
     */
    public static native String[] analogous(Color color, int results, int slices, ColorFormat outputFormat) /*-{
        var ret = $wnd.isc.Colors.analogous(color.@com.smartgwt.client.core.DataClass::getJsObj()(), results, slices, outputFormat == null ? null : outputFormat.@com.smartgwt.client.types.ColorFormat::getValue()());
        if(ret == null) return null;
        return @com.smartgwt.client.util.ConvertTo::arrayOfString(Lcom/google/gwt/core/client/JavaScriptObject;)(ret);
    }-*/;


	/**
     * Returns a text color that meets a target contrast ratio against the given background. Useful for ensuring readability -
     * given any background color, this method finds a foreground color that passes WCAG accessibility guidelines. <P> By
     * default, tries white first (preferred for dark backgrounds) and falls back to black. When <code>tint</code> is true, the
     * result is lightly tinted toward the background's hue for a more polished look, while still meeting the contrast target.
     * @param background the background color to find a readable text color for
     *
     * @return a Color meeting the contrast target, or the best available if the target     cannot be met
     * @see com.smartgwt.client.util.Colors#contrast
     * @see com.smartgwt.client.util.Colors#mostReadable
     */
    public static native Color autoContrast(String background) /*-{
        var ret = $wnd.isc.Colors.autoContrast(background);
        if(ret == null) return null;
        return @com.smartgwt.client.util.Color::getOrCreateRef(Lcom/google/gwt/core/client/JavaScriptObject;)(ret);
    }-*/;

	/**
     * Returns a text color that meets a target contrast ratio against the given background. Useful for ensuring readability -
     * given any background color, this method finds a foreground color that passes WCAG accessibility guidelines. <P> By
     * default, tries white first (preferred for dark backgrounds) and falls back to black. When <code>tint</code> is true, the
     * result is lightly tinted toward the background's hue for a more polished look, while still meeting the contrast target.
     * @param background the background color to find a readable text color for
     *
     * @return a Color meeting the contrast target, or the best available if the target     cannot be met
     * @see com.smartgwt.client.util.Colors#contrast
     * @see com.smartgwt.client.util.Colors#mostReadable
     */
    public static native Color autoContrast(Color background) /*-{
        var ret = $wnd.isc.Colors.autoContrast(background.@com.smartgwt.client.core.DataClass::getJsObj()());
        if(ret == null) return null;
        return @com.smartgwt.client.util.Color::getOrCreateRef(Lcom/google/gwt/core/client/JavaScriptObject;)(ret);
    }-*/;

	/**
     * Returns a text color that meets a target contrast ratio against the given background. Useful for ensuring readability -
     * given any background color, this method finds a foreground color that passes WCAG accessibility guidelines. <P> By
     * default, tries white first (preferred for dark backgrounds) and falls back to black. When <code>tint</code> is true, the
     * result is lightly tinted toward the background's hue for a more polished look, while still meeting the contrast target.
     * @param background the background color to find a readable text color for
     * @param options optional settings:<ul>     <li><code>target</code> - minimum contrast ratio (default 4.5 for WCAG AA; use 7.0 for       
     * WCAG AAA)</li>     <li><code>prefer</code> - <code>"white"</code> (default) or <code>"black"</code>; which        
     * extreme to try first</li>     <li><code>tint</code> - if true, lightly tint the result toward the background's hue      
     *   (default false)</li></ul>
     *
     * @return a Color meeting the contrast target, or the best available if the target     cannot be met
     * @see com.smartgwt.client.util.Colors#contrast
     * @see com.smartgwt.client.util.Colors#mostReadable
     */
    public static native Color autoContrast(String background, Map options) /*-{
        var ret = $wnd.isc.Colors.autoContrast(background, options == null ? null : @com.smartgwt.client.util.JSOHelper::convertMapToJavascriptObject(Ljava/util/Map;)(options));
        if(ret == null) return null;
        return @com.smartgwt.client.util.Color::getOrCreateRef(Lcom/google/gwt/core/client/JavaScriptObject;)(ret);
    }-*/;

	/**
     * Returns a text color that meets a target contrast ratio against the given background. Useful for ensuring readability -
     * given any background color, this method finds a foreground color that passes WCAG accessibility guidelines. <P> By
     * default, tries white first (preferred for dark backgrounds) and falls back to black. When <code>tint</code> is true, the
     * result is lightly tinted toward the background's hue for a more polished look, while still meeting the contrast target.
     * @param background the background color to find a readable text color for
     * @param options optional settings:<ul>     <li><code>target</code> - minimum contrast ratio (default 4.5 for WCAG AA; use 7.0 for       
     * WCAG AAA)</li>     <li><code>prefer</code> - <code>"white"</code> (default) or <code>"black"</code>; which        
     * extreme to try first</li>     <li><code>tint</code> - if true, lightly tint the result toward the background's hue      
     *   (default false)</li></ul>
     *
     * @return a Color meeting the contrast target, or the best available if the target     cannot be met
     * @see com.smartgwt.client.util.Colors#contrast
     * @see com.smartgwt.client.util.Colors#mostReadable
     */
    public static native Color autoContrast(Color background, Map options) /*-{
        var ret = $wnd.isc.Colors.autoContrast(background.@com.smartgwt.client.core.DataClass::getJsObj()(), options == null ? null : @com.smartgwt.client.util.JSOHelper::convertMapToJavascriptObject(Ljava/util/Map;)(options));
        if(ret == null) return null;
        return @com.smartgwt.client.util.Color::getOrCreateRef(Lcom/google/gwt/core/client/JavaScriptObject;)(ret);
    }-*/;


	/**
     * Returns a brighter, more vivid version of the given color by boosting both chroma (color intensity) and lightness
     * together.  This produces an "intensified" highlight rather than a washed-out tint (as {@link
     * com.smartgwt.client.util.Colors#lighten lighten()} alone would) or a hue shift without luminance change (as {@link
     * com.smartgwt.client.util.Colors#saturate saturate()} alone would). <P> A typical use is hover highlighting in charts:
     * the highlighted color should look like a more vibrant version of the base color rather than a lighter or pinker variant.
     * <P> The <code>amount</code> controls both axes: lightness receives the full amount while chroma receives half, keeping
     * the color recognizable at typical hover percentages (25&ndash;40).  For independent control use {@link
     * com.smartgwt.client.util.Colors#adjust adjust()} directly.
     * @param color any valid CSS color string or structured color object
     * @param amount percentage to brighten, 0-100
     *
     * @return CSS color string, or null if the input is not a valid color
     * @see com.smartgwt.client.util.Colors#dim
     * @see com.smartgwt.client.util.Colors#adjust
     */
    public static native String brighten(String color, double amount) /*-{
        var ret = $wnd.isc.Colors.brighten(color, amount);
        return ret;
    }-*/;

	/**
     * Returns a brighter, more vivid version of the given color by boosting both chroma (color intensity) and lightness
     * together.  This produces an "intensified" highlight rather than a washed-out tint (as {@link
     * com.smartgwt.client.util.Colors#lighten lighten()} alone would) or a hue shift without luminance change (as {@link
     * com.smartgwt.client.util.Colors#saturate saturate()} alone would). <P> A typical use is hover highlighting in charts:
     * the highlighted color should look like a more vibrant version of the base color rather than a lighter or pinker variant.
     * <P> The <code>amount</code> controls both axes: lightness receives the full amount while chroma receives half, keeping
     * the color recognizable at typical hover percentages (25&ndash;40).  For independent control use {@link
     * com.smartgwt.client.util.Colors#adjust adjust()} directly.
     * @param color any valid CSS color string or structured color object
     * @param amount percentage to brighten, 0-100
     * @param outputFormat output format; defaults to the detected format of     the input color (hex for named colors)
     *
     * @return CSS color string, or null if the input is not a valid color
     * @see com.smartgwt.client.util.Colors#dim
     * @see com.smartgwt.client.util.Colors#adjust
     */
    public static native String brighten(String color, double amount, ColorFormat outputFormat) /*-{
        var ret = $wnd.isc.Colors.brighten(color, amount, outputFormat == null ? null : outputFormat.@com.smartgwt.client.types.ColorFormat::getValue()());
        return ret;
    }-*/;
	


	/**
     * Returns the complementary color - the hue on the opposite side of the color wheel (rotated by 180 degrees). Equivalent
     * to <code>adjust(color, {h: 180})</code>. <P> Complementary pairs produce maximum hue contrast and are commonly used for
     * accents, call-to-action elements, or alert states against a primary brand color. The oklch hue wheel: red ~30, yellow
     * ~90, green ~145, cyan ~195, blue ~265, purple ~310. Other useful rotations via {@link
     * com.smartgwt.client.util.Colors#adjust adjust()}: +120/-120 for triadic accents, +90/-90 for square-scheme accents.
     * @param color any valid CSS color string or structured color object
     *
     * @return CSS color string, or null if the input is not a valid color
     * @see com.smartgwt.client.util.Colors#adjust
     */
    public static native String complement(String color) /*-{
        var ret = $wnd.isc.Colors.complement(color);
        return ret;
    }-*/;

	/**
     * Returns the complementary color - the hue on the opposite side of the color wheel (rotated by 180 degrees). Equivalent
     * to <code>adjust(color, {h: 180})</code>. <P> Complementary pairs produce maximum hue contrast and are commonly used for
     * accents, call-to-action elements, or alert states against a primary brand color. The oklch hue wheel: red ~30, yellow
     * ~90, green ~145, cyan ~195, blue ~265, purple ~310. Other useful rotations via {@link
     * com.smartgwt.client.util.Colors#adjust adjust()}: +120/-120 for triadic accents, +90/-90 for square-scheme accents.
     * @param color any valid CSS color string or structured color object
     *
     * @return CSS color string, or null if the input is not a valid color
     * @see com.smartgwt.client.util.Colors#adjust
     */
    public static native String complement(Color color) /*-{
        var ret = $wnd.isc.Colors.complement(color.@com.smartgwt.client.core.DataClass::getJsObj()());
        return ret;
    }-*/;

	/**
     * Returns the complementary color - the hue on the opposite side of the color wheel (rotated by 180 degrees). Equivalent
     * to <code>adjust(color, {h: 180})</code>. <P> Complementary pairs produce maximum hue contrast and are commonly used for
     * accents, call-to-action elements, or alert states against a primary brand color. The oklch hue wheel: red ~30, yellow
     * ~90, green ~145, cyan ~195, blue ~265, purple ~310. Other useful rotations via {@link
     * com.smartgwt.client.util.Colors#adjust adjust()}: +120/-120 for triadic accents, +90/-90 for square-scheme accents.
     * @param color any valid CSS color string or structured color object
     * @param outputFormat output format; defaults to the detected format of the     input color (hex for named colors)
     *
     * @return CSS color string, or null if the input is not a valid color
     * @see com.smartgwt.client.util.Colors#adjust
     */
    public static native String complement(String color, ColorFormat outputFormat) /*-{
        var ret = $wnd.isc.Colors.complement(color, outputFormat == null ? null : outputFormat.@com.smartgwt.client.types.ColorFormat::getValue()());
        return ret;
    }-*/;

	/**
     * Returns the complementary color - the hue on the opposite side of the color wheel (rotated by 180 degrees). Equivalent
     * to <code>adjust(color, {h: 180})</code>. <P> Complementary pairs produce maximum hue contrast and are commonly used for
     * accents, call-to-action elements, or alert states against a primary brand color. The oklch hue wheel: red ~30, yellow
     * ~90, green ~145, cyan ~195, blue ~265, purple ~310. Other useful rotations via {@link
     * com.smartgwt.client.util.Colors#adjust adjust()}: +120/-120 for triadic accents, +90/-90 for square-scheme accents.
     * @param color any valid CSS color string or structured color object
     * @param outputFormat output format; defaults to the detected format of the     input color (hex for named colors)
     *
     * @return CSS color string, or null if the input is not a valid color
     * @see com.smartgwt.client.util.Colors#adjust
     */
    public static native String complement(Color color, ColorFormat outputFormat) /*-{
        var ret = $wnd.isc.Colors.complement(color.@com.smartgwt.client.core.DataClass::getJsObj()(), outputFormat == null ? null : outputFormat.@com.smartgwt.client.types.ColorFormat::getValue()());
        return ret;
    }-*/;



	/**
     * Returns a darker version of the given color. Equivalent to <code>adjust(color, {lightness: -amount})</code>. <P> The
     * <code>amount</code> is a percentage (0-100) indicating how far to move toward black: 0 returns the original color, 100
     * returns black. Intermediate values move proportionally - <code>darken(color, 20)</code> always looks like "20% darker"
     * regardless of the starting lightness. <P> For multi-axis adjustments, use {@link com.smartgwt.client.util.Colors#adjust
     * adjust()} directly.
     * @param color any valid CSS color string or structured color object
     * @param amount percentage to darken, 0-100
     *
     * @return CSS color string, or null if the input is not a valid color
     * @see com.smartgwt.client.util.Colors#lighten
     * @see com.smartgwt.client.util.Colors#adjust
     */
    public static native String darken(String color, double amount) /*-{
        var ret = $wnd.isc.Colors.darken(color, amount);
        return ret;
    }-*/;

	/**
     * Returns a darker version of the given color. Equivalent to <code>adjust(color, {lightness: -amount})</code>. <P> The
     * <code>amount</code> is a percentage (0-100) indicating how far to move toward black: 0 returns the original color, 100
     * returns black. Intermediate values move proportionally - <code>darken(color, 20)</code> always looks like "20% darker"
     * regardless of the starting lightness. <P> For multi-axis adjustments, use {@link com.smartgwt.client.util.Colors#adjust
     * adjust()} directly.
     * @param color any valid CSS color string or structured color object
     * @param amount percentage to darken, 0-100
     * @param outputFormat output format; defaults to the detected format of the     input color (hex for named colors)
     *
     * @return CSS color string, or null if the input is not a valid color
     * @see com.smartgwt.client.util.Colors#lighten
     * @see com.smartgwt.client.util.Colors#adjust
     */
    public static native String darken(String color, double amount, ColorFormat outputFormat) /*-{
        var ret = $wnd.isc.Colors.darken(color, amount, outputFormat == null ? null : outputFormat.@com.smartgwt.client.types.ColorFormat::getValue()());
        return ret;
    }-*/;
	

	/**
     * Returns a more muted version of the given color by reducing its chroma (color intensity). Equivalent to
     * <code>adjust(color, {saturation: -amount})</code>. <P> The <code>amount</code> is a percentage (0-100) of chroma to
     * remove: 0 returns the original color, 100 returns a pure gray at the same lightness. <P> For multi-axis adjustments, use
     * {@link com.smartgwt.client.util.Colors#adjust adjust()} directly.
     * @param color any valid CSS color string or structured color object
     * @param amount percentage to desaturate, 0-100
     *
     * @return CSS color string, or null if the input is not a valid color
     * @see com.smartgwt.client.util.Colors#saturate
     * @see com.smartgwt.client.util.Colors#adjust
     */
    public static native String desaturate(String color, double amount) /*-{
        var ret = $wnd.isc.Colors.desaturate(color, amount);
        return ret;
    }-*/;

	/**
     * Returns a more muted version of the given color by reducing its chroma (color intensity). Equivalent to
     * <code>adjust(color, {saturation: -amount})</code>. <P> The <code>amount</code> is a percentage (0-100) of chroma to
     * remove: 0 returns the original color, 100 returns a pure gray at the same lightness. <P> For multi-axis adjustments, use
     * {@link com.smartgwt.client.util.Colors#adjust adjust()} directly.
     * @param color any valid CSS color string or structured color object
     * @param amount percentage to desaturate, 0-100
     * @param outputFormat output format; defaults to the detected format of the     input color (hex for named colors)
     *
     * @return CSS color string, or null if the input is not a valid color
     * @see com.smartgwt.client.util.Colors#saturate
     * @see com.smartgwt.client.util.Colors#adjust
     */
    public static native String desaturate(String color, double amount, ColorFormat outputFormat) /*-{
        var ret = $wnd.isc.Colors.desaturate(color, amount, outputFormat == null ? null : outputFormat.@com.smartgwt.client.types.ColorFormat::getValue()());
        return ret;
    }-*/;
	

	/**
     * Computes the perceptual relationship between two colors in oklch space and returns a structured description. This is the
     * analytical inverse of color manipulation: given a base and a derived color, it tells you what oklch adjustments were
     * applied. <P> For example, a skin has an accent color <code>#3B82F6</code> and a hand-picked hover color
     * <code>#6BA3F8</code>. To find out what the relationship actually is (so it can be expressed as a formula rather than a
     * second hard-coded hex value):  <P> The returned object contains: <ul> <li><b>type</b> - a simplified classification:
     * <code>"lighten"</code>,     <code>"darken"</code>, <code>"saturate"</code>, <code>"desaturate"</code>,    
     * <code>"spin"</code>, <code>"adjust"</code> (multiple significant changes), or     <code>"identical"</code></li>
     * <li><b>L</b> - oklch lightness delta (positive = lighter, 0-1 scale)</li> <li><b>C</b> - oklch chroma delta (positive =
     * more saturated)</li> <li><b>h</b> - oklch hue delta in degrees (shortest-arc rotation, -180 to +180)</li> </ul> <P> The
     * type classification uses perceptual thresholds: L changes &gt; 0.01, C changes &gt; 0.005, and hue changes &gt; 2
     * degrees are considered significant. When exactly one dimension changes significantly, the type reflects that dimension.
     * When multiple dimensions change, the type is <code>"adjust"</code>.
     * @param baseColor the origin/base color
     * @param derivedColor the derived/transformed color
     *
     * @return relationship descriptor with type, L, C, h properties
     * @see com.smartgwt.client.util.Colors#generateCSS
     * @see com.smartgwt.client.util.Colors#parseRelationship
     */
    public static native Map describeRelationship(String baseColor, String derivedColor) /*-{
        var ret = $wnd.isc.Colors.describeRelationship(baseColor, derivedColor);
        return @com.smartgwt.client.util.JSOHelper::convertToMap(Lcom/google/gwt/core/client/JavaScriptObject;)(ret);
    }-*/;


	/**
     * Returns a dimmer, less vivid version of the given color &mdash; the inverse of {@link
     * com.smartgwt.client.util.Colors#brighten brighten()}.  Reduces both chroma and lightness together, producing a muted,
     * subdued appearance.
     * @param color any valid CSS color string or structured color object
     * @param amount percentage to dim, 0-100
     *
     * @return CSS color string, or null if the input is not a valid color
     * @see com.smartgwt.client.util.Colors#brighten
     * @see com.smartgwt.client.util.Colors#adjust
     */
    public static native String dim(String color, double amount) /*-{
        var ret = $wnd.isc.Colors.dim(color, amount);
        return ret;
    }-*/;

	/**
     * Returns a dimmer, less vivid version of the given color &mdash; the inverse of {@link
     * com.smartgwt.client.util.Colors#brighten brighten()}.  Reduces both chroma and lightness together, producing a muted,
     * subdued appearance.
     * @param color any valid CSS color string or structured color object
     * @param amount percentage to dim, 0-100
     * @param outputFormat output format; defaults to the detected format of     the input color (hex for named colors)
     *
     * @return CSS color string, or null if the input is not a valid color
     * @see com.smartgwt.client.util.Colors#brighten
     * @see com.smartgwt.client.util.Colors#adjust
     */
    public static native String dim(String color, double amount, ColorFormat outputFormat) /*-{
        var ret = $wnd.isc.Colors.dim(color, amount, outputFormat == null ? null : outputFormat.@com.smartgwt.client.types.ColorFormat::getValue()());
        return ret;
    }-*/;
	




	/**
     * Converts an oklch relationship descriptor (as returned by {@link com.smartgwt.client.util.Colors#describeRelationship
     * describeRelationship()} or {@link com.smartgwt.client.util.Colors#parseRelationship parseRelationship()}) into a CSS
     * Relative Color Syntax expression. The generated expression uses oklch as the color space, ensuring perceptually uniform
     * transforms. <P> For example, to define a hover color that is always 10% lighter than the theme's accent, regardless of
     * what the accent color actually is:  <P> The <code>origin</code> parameter is the CSS expression to use as the RCS origin
     * - typically a <code>var()</code> reference like <code>"var(--isc-accent)"</code>, but can also be a literal color like
     * <code>"#3B82F6"</code>.
     * @param origin the CSS origin expression for the RCS - typically a     <code>var()</code> reference or a literal color
     * @param relationship an object with oklch deltas: <code>L</code> (lightness),     <code>C</code> (chroma), and/or <code>h</code> (hue).
     * Properties that are zero, null,     or omitted produce identity channel passes. Accepts the output of both     {@link
     * com.smartgwt.client.util.Colors#describeRelationship describeRelationship()} and {@link
     * com.smartgwt.client.util.Colors#parseRelationship parseRelationship()}
     *
     * @return a CSS oklch RCS expression
     * @see com.smartgwt.client.util.Colors#describeRelationship
     * @see com.smartgwt.client.util.Colors#parseRelationship
     * @see com.smartgwt.client.util.Colors#resolveCSS
     */
    public static native String generateCSS(String origin, Map relationship) /*-{
        var ret = $wnd.isc.Colors.generateCSS(origin, relationship == null ? null : @com.smartgwt.client.util.JSOHelper::convertMapToJavascriptObject(Ljava/util/Map;)(relationship));
        return ret;
    }-*/;


	/**
     * Returns the alpha (opacity) component of the given color as a float from 0.0 (fully transparent) to 1.0 (fully opaque).
     * Returns null if the color is not valid. <P> Accepts any valid CSS color string or structured color object. Fully opaque
     * colors that lack an explicit alpha component return 1.0. The keyword <code>"transparent"</code> returns 0.0.
     * @param color any valid CSS color string or structured color object
     *
     * @return alpha component (0.0 - 1.0), or null if invalid
     */
    public static native Double getAlpha(String color) /*-{
        var ret = $wnd.isc.Colors.getAlpha(color);
        if(ret == null) return null;
        return @com.smartgwt.client.util.JSOHelper::toDouble(D)(ret);
    }-*/;

	/**
     * Returns the alpha (opacity) component of the given color as a float from 0.0 (fully transparent) to 1.0 (fully opaque).
     * Returns null if the color is not valid. <P> Accepts any valid CSS color string or structured color object. Fully opaque
     * colors that lack an explicit alpha component return 1.0. The keyword <code>"transparent"</code> returns 0.0.
     * @param color any valid CSS color string or structured color object
     *
     * @return alpha component (0.0 - 1.0), or null if invalid
     */
    public static native Double getAlpha(Color color) /*-{
        var ret = $wnd.isc.Colors.getAlpha(color.@com.smartgwt.client.core.DataClass::getJsObj()());
        if(ret == null) return null;
        return @com.smartgwt.client.util.JSOHelper::toDouble(D)(ret);
    }-*/;


	/**
     * Parses any valid CSS color into a structured {@link com.smartgwt.client.util.Color} object with RGB, HSL, and oklch
     * properties pre-computed, plus convenience methods for manipulation. <P> Accepts any CSS color string (<code>#hex</code>,
     * <code>rgb()</code>, <code>hsl()</code>, <code>oklch()</code>, named colors) or a structured component object in any
     * supported color space: <code>{r, g, b}</code>, <code>{h, s, l}</code>, or <code>{L, C, h}</code>. <P> Also accepts CSS
     * Relative Color Syntax (RCS) expressions with literal color origins, such as <code>rgb(from #3B82F6 calc(r - 0.1) g
     * b)</code>, <code>hsl(from #47a7e3 h s calc(l + 20))</code>, or <code>oklch(from #3B82F6 calc(l + 0.15) c h)</code>. The
     * origin can be any parseable color string - hex, named, or a nested function call. Channel keywords use CSS-native
     * ranges: RGB channels are 0-1 sRGB fractions (not 0-255), HSL s/l are 0-100, oklch L is 0-1.  The origin is resolved, the
     * channel adjustments (bare keywords, <code>calc()</code>, <code>max()</code>, <code>min()</code>) are evaluated, and the
     * result is returned as a fully resolved Color. <P> Also accepts manipulation function-strings such as
     * <code>lighten(#3B82F6, 20)</code>, <code>darken(blue, 15%)</code>, <code>saturate(#abc, 30)</code>, or
     * <code>complement(red)</code>.  Supported function names: <code>lighten</code>, <code>darken</code>,
     * <code>brighten</code>, <code>dim</code>, <code>saturate</code>, <code>desaturate</code>, <code>complement</code>,
     * <code>spin</code>.  The color argument can be any parseable color string; the amount is a number (optionally suffixed
     * with "%"). <code>complement()</code> takes only a color argument.  These are equivalent to calling the corresponding
     * {@link com.smartgwt.client.util.Colors} class method, but expressed as a single string - useful when color expressions
     * come from user input, configuration files, or declarative settings. <P> Expressions containing <code>var()</code>
     * references or <code>color-mix()</code> are automatically resolved through the browser's CSS engine (via {@link
     * com.smartgwt.client.util.Colors#resolveCSS resolveCSS()}). This requires DOM access - on the server, such expressions
     * return an invalid Color. <P> Always returns a {@link com.smartgwt.client.util.Color} object. If the input cannot be
     * parsed, the returned object will have {@link com.smartgwt.client.util.Color#isValid isValid()} returning false
     * (properties default to black). If the input is already a {@link com.smartgwt.client.util.Color}, a new Color with the
     * same values is returned.
     * @param color any valid CSS color string, an existing     {@link com.smartgwt.client.util.Color} (copied), or a structured object with
     * {r,g,b}, {h,s,l}, or     {L,C,h} keys
     *
     * @return a Color object - check {@link com.smartgwt.client.util.Color#isValid isValid()} for parse success
     */
    public static native Color getColor(String color) /*-{
        var ret = $wnd.isc.Colors.getColor(color);
        if(ret == null) return null;
        return @com.smartgwt.client.util.Color::getOrCreateRef(Lcom/google/gwt/core/client/JavaScriptObject;)(ret);
    }-*/;

	/**
     * Parses any valid CSS color into a structured {@link com.smartgwt.client.util.Color} object with RGB, HSL, and oklch
     * properties pre-computed, plus convenience methods for manipulation. <P> Accepts any CSS color string (<code>#hex</code>,
     * <code>rgb()</code>, <code>hsl()</code>, <code>oklch()</code>, named colors) or a structured component object in any
     * supported color space: <code>{r, g, b}</code>, <code>{h, s, l}</code>, or <code>{L, C, h}</code>. <P> Also accepts CSS
     * Relative Color Syntax (RCS) expressions with literal color origins, such as <code>rgb(from #3B82F6 calc(r - 0.1) g
     * b)</code>, <code>hsl(from #47a7e3 h s calc(l + 20))</code>, or <code>oklch(from #3B82F6 calc(l + 0.15) c h)</code>. The
     * origin can be any parseable color string - hex, named, or a nested function call. Channel keywords use CSS-native
     * ranges: RGB channels are 0-1 sRGB fractions (not 0-255), HSL s/l are 0-100, oklch L is 0-1.  The origin is resolved, the
     * channel adjustments (bare keywords, <code>calc()</code>, <code>max()</code>, <code>min()</code>) are evaluated, and the
     * result is returned as a fully resolved Color. <P> Also accepts manipulation function-strings such as
     * <code>lighten(#3B82F6, 20)</code>, <code>darken(blue, 15%)</code>, <code>saturate(#abc, 30)</code>, or
     * <code>complement(red)</code>.  Supported function names: <code>lighten</code>, <code>darken</code>,
     * <code>brighten</code>, <code>dim</code>, <code>saturate</code>, <code>desaturate</code>, <code>complement</code>,
     * <code>spin</code>.  The color argument can be any parseable color string; the amount is a number (optionally suffixed
     * with "%"). <code>complement()</code> takes only a color argument.  These are equivalent to calling the corresponding
     * {@link com.smartgwt.client.util.Colors} class method, but expressed as a single string - useful when color expressions
     * come from user input, configuration files, or declarative settings. <P> Expressions containing <code>var()</code>
     * references or <code>color-mix()</code> are automatically resolved through the browser's CSS engine (via {@link
     * com.smartgwt.client.util.Colors#resolveCSS resolveCSS()}). This requires DOM access - on the server, such expressions
     * return an invalid Color. <P> Always returns a {@link com.smartgwt.client.util.Color} object. If the input cannot be
     * parsed, the returned object will have {@link com.smartgwt.client.util.Color#isValid isValid()} returning false
     * (properties default to black). If the input is already a {@link com.smartgwt.client.util.Color}, a new Color with the
     * same values is returned.
     * @param color any valid CSS color string, an existing     {@link com.smartgwt.client.util.Color} (copied), or a structured object with
     * {r,g,b}, {h,s,l}, or     {L,C,h} keys
     *
     * @return a Color object - check {@link com.smartgwt.client.util.Color#isValid isValid()} for parse success
     */
    public static native Color getColor(Color color) /*-{
        var ret = $wnd.isc.Colors.getColor(color.@com.smartgwt.client.core.DataClass::getJsObj()());
        if(ret == null) return null;
        return @com.smartgwt.client.util.Color::getOrCreateRef(Lcom/google/gwt/core/client/JavaScriptObject;)(ret);
    }-*/;

	/**
     * Parses any valid CSS color into a structured {@link com.smartgwt.client.util.Color} object with RGB, HSL, and oklch
     * properties pre-computed, plus convenience methods for manipulation. <P> Accepts any CSS color string (<code>#hex</code>,
     * <code>rgb()</code>, <code>hsl()</code>, <code>oklch()</code>, named colors) or a structured component object in any
     * supported color space: <code>{r, g, b}</code>, <code>{h, s, l}</code>, or <code>{L, C, h}</code>. <P> Also accepts CSS
     * Relative Color Syntax (RCS) expressions with literal color origins, such as <code>rgb(from #3B82F6 calc(r - 0.1) g
     * b)</code>, <code>hsl(from #47a7e3 h s calc(l + 20))</code>, or <code>oklch(from #3B82F6 calc(l + 0.15) c h)</code>. The
     * origin can be any parseable color string - hex, named, or a nested function call. Channel keywords use CSS-native
     * ranges: RGB channels are 0-1 sRGB fractions (not 0-255), HSL s/l are 0-100, oklch L is 0-1.  The origin is resolved, the
     * channel adjustments (bare keywords, <code>calc()</code>, <code>max()</code>, <code>min()</code>) are evaluated, and the
     * result is returned as a fully resolved Color. <P> Also accepts manipulation function-strings such as
     * <code>lighten(#3B82F6, 20)</code>, <code>darken(blue, 15%)</code>, <code>saturate(#abc, 30)</code>, or
     * <code>complement(red)</code>.  Supported function names: <code>lighten</code>, <code>darken</code>,
     * <code>brighten</code>, <code>dim</code>, <code>saturate</code>, <code>desaturate</code>, <code>complement</code>,
     * <code>spin</code>.  The color argument can be any parseable color string; the amount is a number (optionally suffixed
     * with "%"). <code>complement()</code> takes only a color argument.  These are equivalent to calling the corresponding
     * {@link com.smartgwt.client.util.Colors} class method, but expressed as a single string - useful when color expressions
     * come from user input, configuration files, or declarative settings. <P> Expressions containing <code>var()</code>
     * references or <code>color-mix()</code> are automatically resolved through the browser's CSS engine (via {@link
     * com.smartgwt.client.util.Colors#resolveCSS resolveCSS()}). This requires DOM access - on the server, such expressions
     * return an invalid Color. <P> Always returns a {@link com.smartgwt.client.util.Color} object. If the input cannot be
     * parsed, the returned object will have {@link com.smartgwt.client.util.Color#isValid isValid()} returning false
     * (properties default to black). If the input is already a {@link com.smartgwt.client.util.Color}, a new Color with the
     * same values is returned.
     * @param color any valid CSS color string, an existing     {@link com.smartgwt.client.util.Color} (copied), or a structured object with
     * {r,g,b}, {h,s,l}, or     {L,C,h} keys
     *
     * @return a Color object - check {@link com.smartgwt.client.util.Color#isValid isValid()} for parse success
     */
    public static native Color getColor(Map color) /*-{
        var ret = $wnd.isc.Colors.getColor(color == null ? null : @com.smartgwt.client.util.JSOHelper::convertMapToJavascriptObject(Ljava/util/Map;)(color));
        if(ret == null) return null;
        return @com.smartgwt.client.util.Color::getOrCreateRef(Lcom/google/gwt/core/client/JavaScriptObject;)(ret);
    }-*/;


	/**
     * Returns the {@link com.smartgwt.client.types.ColorFormat} of the given color string, or null if the value is not a valid
     * color. For named colors (e.g. "red") and "transparent", the format is reported as <code>"hex"</code> since the canonical
     * representation is hexadecimal.
     * @param color a CSS color string
     *
     * @return the detected format, or null if invalid
     */
    public static native ColorFormat getFormat(String color) /*-{
        var ret = $wnd.isc.Colors.getFormat(color);
        if(ret == null) return null;
        var enumValues = @com.smartgwt.client.types.ColorFormat::values()();
        return @com.smartgwt.client.util.EnumUtil::getEnum([Lcom/smartgwt/client/types/ValueEnum;Ljava/lang/String;)(enumValues, ret);
    }-*/;


	/**
     * Converts any valid CSS color to a string in the specified format. Accepts a CSS color string or a structured color
     * object (as returned by {@link com.smartgwt.client.util.Colors#getColor getColor()}). Returns null if the input is not a
     * valid color or the format is unrecognized. <P> Supported target formats: <ul> <li><code>"hex"</code> - "#RRGGBB" when
     * opaque, "#RRGGBBAA" when semi-transparent <li><code>"rgb"</code> - "rgb(R, G, B)" when opaque, "rgba(R, G, B, A)" when
     * semi-transparent <li><code>"hsl"</code> - "hsl(H, S%, L%)" when opaque, "hsla(H, S%, L%, A)" when     semi-transparent
     * <li><code>"oklch"</code> - "oklch(L% C h)" when opaque, "oklch(L% C h / A)" when     semi-transparent </ul>
     * @param color any valid CSS color string, or a structured color object with     {r,g,b}, {h,s,l}, or {L,C,h} keys
     * @param format target format: "hex", "rgb", "hsl", or "oklch"
     *
     * @return CSS color string in the target format, or null
     */
    public static native String getString(String color, ColorFormat format) /*-{
        var ret = $wnd.isc.Colors.getString(color, format.@com.smartgwt.client.types.ColorFormat::getValue()());
        return ret;
    }-*/;


	/**
     * Returns a plain object with color component values in the requested format. Unlike {@link
     * com.smartgwt.client.util.Colors#getColor getColor()}, which returns a full {@link com.smartgwt.client.util.Color} object
     * with methods and properties in all color spaces, this returns only the numeric components for the requested format -
     * useful when you need raw values for computation without the overhead of a full Color, or when passing components to
     * external APIs. <P> Supported formats and their returned keys: <ul> <li><code>"rgb"</code> - <code>{r, g, b,
     * alpha}</code> (0-255 integers, alpha 0-1) <li><code>"hsl"</code> - <code>{h, s, l, alpha}</code> (h: 0-360 degrees, s/l:
     * 0-100     percent, alpha 0-1) <li><code>"oklch"</code> - <code>{L, C, h, alpha}</code> (L: 0-1 lightness, C: 0+ chroma, 
     *    h: 0-360 degrees, alpha 0-1) </ul>
     * @param color any valid CSS color string or {@link com.smartgwt.client.util.Color}
     * @param format target format: "rgb", "hsl", or "oklch"
     *
     * @return plain object with numeric component keys, or null if invalid
     * @see com.smartgwt.client.util.Colors#getColor
     * @see com.smartgwt.client.util.Colors#getString
     */
    public static native Map getValues(String color, ColorFormat format) /*-{
        var ret = $wnd.isc.Colors.getValues(color, format.@com.smartgwt.client.types.ColorFormat::getValue()());
        return @com.smartgwt.client.util.JSOHelper::convertToMap(Lcom/google/gwt/core/client/JavaScriptObject;)(ret);
    }-*/;


	/**
     * Returns true if the given value is a valid CSS color specification. Accepts any format: hex (#RGB, #RRGGBB, #RRGGBBAA),
     * rgb(), rgba(), hsl(), hsla(), oklch(), named colors, "transparent", CSS Relative Color Syntax expressions, and
     * <code>var()</code> or <code>color-mix()</code> expressions (resolved via the browser's CSS engine when a DOM is
     * available; returns false server-side). <P> If <code>format</code> is specified, the value must be parseable in that
     * particular format (or be "transparent", which is always valid).
     * @param color value to test
     *
     * @return true if the value represents a valid color
     */
    public static native boolean isColor(String color) /*-{
        var ret = $wnd.isc.Colors.isColor(color);
        return ret == null ? false : ret;
    }-*/;

	/**
     * Returns true if the given value is a valid CSS color specification. Accepts any format: hex (#RGB, #RRGGBB, #RRGGBBAA),
     * rgb(), rgba(), hsl(), hsla(), oklch(), named colors, "transparent", CSS Relative Color Syntax expressions, and
     * <code>var()</code> or <code>color-mix()</code> expressions (resolved via the browser's CSS engine when a DOM is
     * available; returns false server-side). <P> If <code>format</code> is specified, the value must be parseable in that
     * particular format (or be "transparent", which is always valid).
     * @param color value to test
     *
     * @return true if the value represents a valid color
     */
    public static native boolean isColor(Color color) /*-{
        var ret = $wnd.isc.Colors.isColor(color.@com.smartgwt.client.core.DataClass::getJsObj()());
        return ret == null ? false : ret;
    }-*/;

	/**
     * Returns true if the given value is a valid CSS color specification. Accepts any format: hex (#RGB, #RRGGBB, #RRGGBBAA),
     * rgb(), rgba(), hsl(), hsla(), oklch(), named colors, "transparent", CSS Relative Color Syntax expressions, and
     * <code>var()</code> or <code>color-mix()</code> expressions (resolved via the browser's CSS engine when a DOM is
     * available; returns false server-side). <P> If <code>format</code> is specified, the value must be parseable in that
     * particular format (or be "transparent", which is always valid).
     * @param color value to test
     *
     * @return true if the value represents a valid color
     */
    public static native boolean isColor(Map color) /*-{
        var ret = $wnd.isc.Colors.isColor(color == null ? null : @com.smartgwt.client.util.JSOHelper::convertMapToJavascriptObject(Ljava/util/Map;)(color));
        return ret == null ? false : ret;
    }-*/;

	/**
     * Returns true if the given value is a valid CSS color specification. Accepts any format: hex (#RGB, #RRGGBB, #RRGGBBAA),
     * rgb(), rgba(), hsl(), hsla(), oklch(), named colors, "transparent", CSS Relative Color Syntax expressions, and
     * <code>var()</code> or <code>color-mix()</code> expressions (resolved via the browser's CSS engine when a DOM is
     * available; returns false server-side). <P> If <code>format</code> is specified, the value must be parseable in that
     * particular format (or be "transparent", which is always valid).
     * @param color value to test
     * @param format if specified, require this format
     *
     * @return true if the value represents a valid color
     */
    public static native boolean isColor(String color, ColorFormat format) /*-{
        var ret = $wnd.isc.Colors.isColor(color, format == null ? null : format.@com.smartgwt.client.types.ColorFormat::getValue()());
        return ret == null ? false : ret;
    }-*/;

	/**
     * Returns true if the given value is a valid CSS color specification. Accepts any format: hex (#RGB, #RRGGBB, #RRGGBBAA),
     * rgb(), rgba(), hsl(), hsla(), oklch(), named colors, "transparent", CSS Relative Color Syntax expressions, and
     * <code>var()</code> or <code>color-mix()</code> expressions (resolved via the browser's CSS engine when a DOM is
     * available; returns false server-side). <P> If <code>format</code> is specified, the value must be parseable in that
     * particular format (or be "transparent", which is always valid).
     * @param color value to test
     * @param format if specified, require this format
     *
     * @return true if the value represents a valid color
     */
    public static native boolean isColor(Color color, ColorFormat format) /*-{
        var ret = $wnd.isc.Colors.isColor(color.@com.smartgwt.client.core.DataClass::getJsObj()(), format == null ? null : format.@com.smartgwt.client.types.ColorFormat::getValue()());
        return ret == null ? false : ret;
    }-*/;

	/**
     * Returns true if the given value is a valid CSS color specification. Accepts any format: hex (#RGB, #RRGGBB, #RRGGBBAA),
     * rgb(), rgba(), hsl(), hsla(), oklch(), named colors, "transparent", CSS Relative Color Syntax expressions, and
     * <code>var()</code> or <code>color-mix()</code> expressions (resolved via the browser's CSS engine when a DOM is
     * available; returns false server-side). <P> If <code>format</code> is specified, the value must be parseable in that
     * particular format (or be "transparent", which is always valid).
     * @param color value to test
     * @param format if specified, require this format
     *
     * @return true if the value represents a valid color
     */
    public static native boolean isColor(Map color, ColorFormat format) /*-{
        var ret = $wnd.isc.Colors.isColor(color == null ? null : @com.smartgwt.client.util.JSOHelper::convertMapToJavascriptObject(Ljava/util/Map;)(color), format == null ? null : format.@com.smartgwt.client.types.ColorFormat::getValue()());
        return ret == null ? false : ret;
    }-*/;


	/**
     * Returns true if the given color is perceptually dark (i.e. would need light foreground text for readability), false if
     * it is light. Uses oklch lightness, which is perceptually uniform - unlike RGB or HSL brightness, a threshold of 0.6
     * consistently separates light from dark colors across hues. Use <code>!isDark(color)</code> to test for lightness. <P>
     * Returns null if the color is not valid.
     * @param color any valid CSS color string or structured color object
     *
     * @return true if perceptually dark, false if light, null if invalid
     */
    public static native Boolean isDark(String color) /*-{
        var ret = $wnd.isc.Colors.isDark(color);
        if(ret == null) return null;
        return @com.smartgwt.client.util.JSOHelper::toBoolean(Z)(ret);
    }-*/;

	/**
     * Returns true if the given color is perceptually dark (i.e. would need light foreground text for readability), false if
     * it is light. Uses oklch lightness, which is perceptually uniform - unlike RGB or HSL brightness, a threshold of 0.6
     * consistently separates light from dark colors across hues. Use <code>!isDark(color)</code> to test for lightness. <P>
     * Returns null if the color is not valid.
     * @param color any valid CSS color string or structured color object
     *
     * @return true if perceptually dark, false if light, null if invalid
     */
    public static native Boolean isDark(Color color) /*-{
        var ret = $wnd.isc.Colors.isDark(color.@com.smartgwt.client.core.DataClass::getJsObj()());
        if(ret == null) return null;
        return @com.smartgwt.client.util.JSOHelper::toBoolean(Z)(ret);
    }-*/;


	/**
     * Returns a lighter version of the given color. Equivalent to <code>adjust(color, {lightness: amount})</code>. <P> The
     * <code>amount</code> is a percentage (0-100) indicating how far to move toward white: 0 returns the original color, 100
     * returns white. Intermediate values move proportionally - <code>lighten(color, 20)</code> on a dark color produces a
     * bigger absolute lightness change than on an already-light color, but both look like "20% lighter" perceptually. <P> For
     * multi-axis adjustments (e.g. lighten and desaturate together), use {@link com.smartgwt.client.util.Colors#adjust
     * adjust()} directly.
     * @param color any valid CSS color string or structured color object
     * @param amount percentage to lighten, 0-100
     *
     * @return CSS color string, or null if the input is not a valid color
     * @see com.smartgwt.client.util.Colors#darken
     * @see com.smartgwt.client.util.Colors#adjust
     */
    public static native String lighten(String color, double amount) /*-{
        var ret = $wnd.isc.Colors.lighten(color, amount);
        return ret;
    }-*/;

	/**
     * Returns a lighter version of the given color. Equivalent to <code>adjust(color, {lightness: amount})</code>. <P> The
     * <code>amount</code> is a percentage (0-100) indicating how far to move toward white: 0 returns the original color, 100
     * returns white. Intermediate values move proportionally - <code>lighten(color, 20)</code> on a dark color produces a
     * bigger absolute lightness change than on an already-light color, but both look like "20% lighter" perceptually. <P> For
     * multi-axis adjustments (e.g. lighten and desaturate together), use {@link com.smartgwt.client.util.Colors#adjust
     * adjust()} directly.
     * @param color any valid CSS color string or structured color object
     * @param amount percentage to lighten, 0-100
     * @param outputFormat output format; defaults to the detected format of the     input color (hex for named colors)
     *
     * @return CSS color string, or null if the input is not a valid color
     * @see com.smartgwt.client.util.Colors#darken
     * @see com.smartgwt.client.util.Colors#adjust
     */
    public static native String lighten(String color, double amount, ColorFormat outputFormat) /*-{
        var ret = $wnd.isc.Colors.lighten(color, amount, outputFormat == null ? null : outputFormat.@com.smartgwt.client.types.ColorFormat::getValue()());
        return ret;
    }-*/;
	


	/**
     * Returns the color from <code>candidates</code> that has the highest contrast against <code> background</code>. Useful
     * for choosing a text color that will be readable on a given background - typically called with <code>["#ffffff",
     * "#000000"]</code> as candidates.
     * @param background the background color to test against
     * @param candidates list of candidate foreground colors
     *
     * @return the candidate with the highest contrast ratio, or null if inputs invalid
     */
    public static native String mostReadable(String background, String[] candidates) /*-{
        var ret = $wnd.isc.Colors.mostReadable(background, @com.smartgwt.client.util.JSOHelper::convertToJavaScriptArray([Ljava/lang/Object;)(candidates));
        return ret;
    }-*/;


	/**
     * Generates a tonal ramp - an ordered series of colors at different lightness levels sharing the same hue. In color
     * theory, lighter variants of a color are called <i>tints</i> (mixed toward white) and darker variants are called
     * <i>shades</i> (mixed toward black); this method produces both in a single ramp. This is the core operation for theme
     * generation: one brand color in, a full light-to-dark palette out. <P> At its simplest, <code>palette("#3366CC",
     * 7)</code> produces 7 stops from dark to light - usable directly as skin backgrounds, hover fills, text colors, and
     * borders. With no options, it uses sensible defaults: a natural chroma curve (vivid in the mid-range, muted at extremes)
     * and a subtle hue shift for a professional, non-flat appearance. <P> For a plain lightness scale with no chroma or hue
     * variation, pass <code>{ chromaCurve: "constant", hueShift: 0 }</code>.  <P> All returned colors are guaranteed to be
     * within the sRGB gamut (via automatic chroma reduction at the extremes). The seed color's own lightness determines where
     * in the ramp it falls - it is not forced to a specific stop index.
     * @param color the seed color whose hue and chroma define the palette
     *
     * @return array of Color objects ordered from darkest to lightest
     * @see com.smartgwt.client.util.Colors#scheme
     * @see com.smartgwt.client.util.Colors#colorScale
     * @see com.smartgwt.client.util.Colors#autoContrast
     */
    public static native Color[] palette(String color) /*-{
        var ret = $wnd.isc.Colors.palette(color);
        if(ret == null) return null;
        return @com.smartgwt.client.util.ConvertTo::arrayOfColor(Lcom/google/gwt/core/client/JavaScriptObject;)(ret);
    }-*/;

	/**
     * Generates a tonal ramp - an ordered series of colors at different lightness levels sharing the same hue. In color
     * theory, lighter variants of a color are called <i>tints</i> (mixed toward white) and darker variants are called
     * <i>shades</i> (mixed toward black); this method produces both in a single ramp. This is the core operation for theme
     * generation: one brand color in, a full light-to-dark palette out. <P> At its simplest, <code>palette("#3366CC",
     * 7)</code> produces 7 stops from dark to light - usable directly as skin backgrounds, hover fills, text colors, and
     * borders. With no options, it uses sensible defaults: a natural chroma curve (vivid in the mid-range, muted at extremes)
     * and a subtle hue shift for a professional, non-flat appearance. <P> For a plain lightness scale with no chroma or hue
     * variation, pass <code>{ chromaCurve: "constant", hueShift: 0 }</code>.  <P> All returned colors are guaranteed to be
     * within the sRGB gamut (via automatic chroma reduction at the extremes). The seed color's own lightness determines where
     * in the ramp it falls - it is not forced to a specific stop index.
     * @param color the seed color whose hue and chroma define the palette
     *
     * @return array of Color objects ordered from darkest to lightest
     * @see com.smartgwt.client.util.Colors#scheme
     * @see com.smartgwt.client.util.Colors#colorScale
     * @see com.smartgwt.client.util.Colors#autoContrast
     */
    public static native Color[] palette(Color color) /*-{
        var ret = $wnd.isc.Colors.palette(color.@com.smartgwt.client.core.DataClass::getJsObj()());
        if(ret == null) return null;
        return @com.smartgwt.client.util.ConvertTo::arrayOfColor(Lcom/google/gwt/core/client/JavaScriptObject;)(ret);
    }-*/;

    /**
     * See {@link Colors#palette(java.lang.String, int, Map) palette()}
     */
    public static Color[] palette(String color, int steps){
        return palette(color, steps, null);
    }

    /**
     * See {@link Colors#palette(com.smartgwt.client.util.Color, int, Map) palette()}
     */
    public static Color[] palette(Color color, int steps){
        return palette(color, steps, null);
    }
	/**
     * Generates a tonal ramp - an ordered series of colors at different lightness levels sharing the same hue. In color
     * theory, lighter variants of a color are called <i>tints</i> (mixed toward white) and darker variants are called
     * <i>shades</i> (mixed toward black); this method produces both in a single ramp. This is the core operation for theme
     * generation: one brand color in, a full light-to-dark palette out. <P> At its simplest, <code>palette("#3366CC",
     * 7)</code> produces 7 stops from dark to light - usable directly as skin backgrounds, hover fills, text colors, and
     * borders. With no options, it uses sensible defaults: a natural chroma curve (vivid in the mid-range, muted at extremes)
     * and a subtle hue shift for a professional, non-flat appearance. <P> For a plain lightness scale with no chroma or hue
     * variation, pass <code>{ chromaCurve: "constant", hueShift: 0 }</code>.  <P> All returned colors are guaranteed to be
     * within the sRGB gamut (via automatic chroma reduction at the extremes). The seed color's own lightness determines where
     * in the ramp it falls - it is not forced to a specific stop index.
     * @param color the seed color whose hue and chroma define the palette
     * @param steps number of stops to generate (default 11)
     * @param options optional settings:<ul>     <li><code>lightnessRange</code> - two-element array of oklch L values for the darkest and    
     * lightest stops (default <code>[0.15, 0.97]</code>)</li>     <li><code>chromaCurve</code> - <code>"natural"</code>
     * (default) tapers chroma toward         extremes using a cosine curve; <code>"constant"</code> uses the seed's chroma for
     * all         stops; <code>"peaked"</code> pushes maximum chroma to a configurable lightness</li>    
     * <li><code>hueShift</code> - degrees of hue rotation across the full lightness range         (default ~4; set to 0 to
     * disable). Positive values shift lighter stops toward warmer         hues.</li></ul>
     *
     * @return array of Color objects ordered from darkest to lightest
     * @see com.smartgwt.client.util.Colors#scheme
     * @see com.smartgwt.client.util.Colors#colorScale
     * @see com.smartgwt.client.util.Colors#autoContrast
     */
    public static native Color[] palette(String color, int steps, Map options) /*-{
        var ret = $wnd.isc.Colors.palette(color, steps, options == null ? null : @com.smartgwt.client.util.JSOHelper::convertMapToJavascriptObject(Ljava/util/Map;)(options));
        if(ret == null) return null;
        return @com.smartgwt.client.util.ConvertTo::arrayOfColor(Lcom/google/gwt/core/client/JavaScriptObject;)(ret);
    }-*/;

	/**
     * Generates a tonal ramp - an ordered series of colors at different lightness levels sharing the same hue. In color
     * theory, lighter variants of a color are called <i>tints</i> (mixed toward white) and darker variants are called
     * <i>shades</i> (mixed toward black); this method produces both in a single ramp. This is the core operation for theme
     * generation: one brand color in, a full light-to-dark palette out. <P> At its simplest, <code>palette("#3366CC",
     * 7)</code> produces 7 stops from dark to light - usable directly as skin backgrounds, hover fills, text colors, and
     * borders. With no options, it uses sensible defaults: a natural chroma curve (vivid in the mid-range, muted at extremes)
     * and a subtle hue shift for a professional, non-flat appearance. <P> For a plain lightness scale with no chroma or hue
     * variation, pass <code>{ chromaCurve: "constant", hueShift: 0 }</code>.  <P> All returned colors are guaranteed to be
     * within the sRGB gamut (via automatic chroma reduction at the extremes). The seed color's own lightness determines where
     * in the ramp it falls - it is not forced to a specific stop index.
     * @param color the seed color whose hue and chroma define the palette
     * @param steps number of stops to generate (default 11)
     * @param options optional settings:<ul>     <li><code>lightnessRange</code> - two-element array of oklch L values for the darkest and    
     * lightest stops (default <code>[0.15, 0.97]</code>)</li>     <li><code>chromaCurve</code> - <code>"natural"</code>
     * (default) tapers chroma toward         extremes using a cosine curve; <code>"constant"</code> uses the seed's chroma for
     * all         stops; <code>"peaked"</code> pushes maximum chroma to a configurable lightness</li>    
     * <li><code>hueShift</code> - degrees of hue rotation across the full lightness range         (default ~4; set to 0 to
     * disable). Positive values shift lighter stops toward warmer         hues.</li></ul>
     *
     * @return array of Color objects ordered from darkest to lightest
     * @see com.smartgwt.client.util.Colors#scheme
     * @see com.smartgwt.client.util.Colors#colorScale
     * @see com.smartgwt.client.util.Colors#autoContrast
     */
    public static native Color[] palette(Color color, int steps, Map options) /*-{
        var ret = $wnd.isc.Colors.palette(color.@com.smartgwt.client.core.DataClass::getJsObj()(), steps, options == null ? null : @com.smartgwt.client.util.JSOHelper::convertMapToJavascriptObject(Ljava/util/Map;)(options));
        if(ret == null) return null;
        return @com.smartgwt.client.util.ConvertTo::arrayOfColor(Lcom/google/gwt/core/client/JavaScriptObject;)(ret);
    }-*/;


	/**
     * Extracts structural information from a CSS Relative Color Syntax (RCS) expression - the origin reference, color space,
     * and per-channel modifications - without evaluating it. This is pure string parsing: no DOM access and no color
     * resolution. It works with any origin, including <code>var()</code> references (which {@link
     * com.smartgwt.client.util.Colors#getColor getColor()} would resolve via the DOM - parseRelationship preserves the raw
     * reference for structural inspection). <P> For example, a skin config stores <code>oklch(from var(--isc-accent) calc(l +
     * 0.15) c h)</code> for a hover color. <code>parseRelationship()</code> extracts the structure so you can see what is
     * being derived from what, without needing to resolve the colors:  <P> The returned object describes the expression's
     * structure: <ul> <li><b>origin</b> - the raw origin string as it appears in the expression (e.g.    
     * <code>"var(--isc-accent)"</code>, <code>"#ff0000"</code>). If the origin is a     <code>var()</code> reference, the
     * caller must use {@link com.smartgwt.client.util.Colors#resolveCSS resolveCSS()} to resolve     it to an actual color -
     * {@link com.smartgwt.client.util.Colors#getColor getColor()} cannot resolve     <code>var()</code> references.</li>
     * <li><b>space</b> - the color space: <code>"rgb"</code>, <code>"hsl"</code>, or     <code>"oklch"</code></li>
     * <li><b>deltas</b> - an object mapping channel names to their additive delta (only channels     that differ from
     * identity). For example, <code>{l: 0.15}</code> means lightness is     shifted by +0.15 while other channels pass through
     * unchanged. Channels with complex     expressions (multiplication, clamping via max/min) are omitted from deltas but
     * present     in rawChannels.</li> <li><b>rawChannels</b> - an array of three raw channel expression strings in CSS order,
     * useful for complex expressions that cannot be reduced to a simple delta</li> <li><b>alpha</b> - the alpha value (1.0 if
     * not specified)</li> </ul> <P> Returns null if the expression is not valid RCS syntax (plain hex, rgb(), named colors,
     * and <code>color-mix()</code> are not RCS and will return null).
     * @param rcsExpr a CSS RCS expression, e.g.     <code>"oklch(from var(--x) calc(l + 0.15) c h)"</code>
     *
     * @return structured descriptor, or null if not valid RCS
     * @see com.smartgwt.client.util.Colors#resolveCSS
     * @see com.smartgwt.client.util.Colors#generateCSS
     */
    public static native Map parseRelationship(String rcsExpr) /*-{
        var ret = $wnd.isc.Colors.parseRelationship(rcsExpr);
        return @com.smartgwt.client.util.JSOHelper::convertToMap(Lcom/google/gwt/core/client/JavaScriptObject;)(ret);
    }-*/;


	/**
     * Resolves any CSS color expression to a flat {@link com.smartgwt.client.util.Color} by evaluating it through the
     * browser's CSS engine. Handles <code>var()</code> references, <code>color-mix()</code>, and any other CSS color
     * constructs supported by the current browser. <P> {@link com.smartgwt.client.util.Colors#getColor getColor()}
     * automatically delegates to this method for expressions containing <code>var()</code> or <code>color-mix()</code>, so
     * most callers never need to call <code>resolveCSS()</code> directly. The main reason to use it explicitly is when you
     * need to pass an <code>element</code> context for inherited CSS custom properties:  <P> Internally, a scratch DOM
     * element's <code>color</code> style is set to the expression and <code>getComputedStyle()</code> reads back the
     * browser-resolved value. If an <code>element</code> is provided, the scratch element is temporarily appended as its
     * child, allowing inherited CSS custom properties to resolve correctly. <P> Returns an invalid Color (with {@link
     * com.smartgwt.client.util.Color#isValid isValid()} false) if the expression is not a valid CSS color in the current
     * browser, or if no DOM is available (e.g. server-side).
     * @param expr any CSS color expression - hex, rgb(), hsl(), oklch(), color-mix(),     var() references, RCS expressions, or any
     * combination the browser supports
     *
     * @return resolved Color object, or an invalid Color if the expression could not be     resolved
     * @see com.smartgwt.client.util.Colors#getColor
     * @see com.smartgwt.client.util.Colors#parseRelationship
     */
    public static native Color resolveCSS(String expr) /*-{
        var ret = $wnd.isc.Colors.resolveCSS(expr);
        if(ret == null) return null;
        return @com.smartgwt.client.util.Color::getOrCreateRef(Lcom/google/gwt/core/client/JavaScriptObject;)(ret);
    }-*/;

	/**
     * Resolves any CSS color expression to a flat {@link com.smartgwt.client.util.Color} by evaluating it through the
     * browser's CSS engine. Handles <code>var()</code> references, <code>color-mix()</code>, and any other CSS color
     * constructs supported by the current browser. <P> {@link com.smartgwt.client.util.Colors#getColor getColor()}
     * automatically delegates to this method for expressions containing <code>var()</code> or <code>color-mix()</code>, so
     * most callers never need to call <code>resolveCSS()</code> directly. The main reason to use it explicitly is when you
     * need to pass an <code>element</code> context for inherited CSS custom properties:  <P> Internally, a scratch DOM
     * element's <code>color</code> style is set to the expression and <code>getComputedStyle()</code> reads back the
     * browser-resolved value. If an <code>element</code> is provided, the scratch element is temporarily appended as its
     * child, allowing inherited CSS custom properties to resolve correctly. <P> Returns an invalid Color (with {@link
     * com.smartgwt.client.util.Color#isValid isValid()} false) if the expression is not a valid CSS color in the current
     * browser, or if no DOM is available (e.g. server-side).
     * @param expr any CSS color expression - hex, rgb(), hsl(), oklch(), color-mix(),     var() references, RCS expressions, or any
     * combination the browser supports
     * @param element optional DOM element to use as the resolution context; if     provided, CSS custom properties inherited by this element
     * will be available for     <code>var()</code> resolution
     *
     * @return resolved Color object, or an invalid Color if the expression could not be     resolved
     * @see com.smartgwt.client.util.Colors#getColor
     * @see com.smartgwt.client.util.Colors#parseRelationship
     */
    public static native Color resolveCSS(String expr, Element element) /*-{
        var ret = $wnd.isc.Colors.resolveCSS(expr, element);
        if(ret == null) return null;
        return @com.smartgwt.client.util.Color::getOrCreateRef(Lcom/google/gwt/core/client/JavaScriptObject;)(ret);
    }-*/;
	

	/**
     * Returns a more vivid version of the given color by increasing its chroma (color intensity). Equivalent to
     * <code>adjust(color, {saturation: amount})</code>. <P> The <code>amount</code> is a percentage (0-100) of additional
     * chroma to add, scaled relative to a practical maximum. A gray color (chroma 0) saturated by 50 produces a clearly
     * visible color; 100 gives full vivid saturation. <P> For multi-axis adjustments, use {@link
     * com.smartgwt.client.util.Colors#adjust adjust()} directly.
     * @param color any valid CSS color string or structured color object
     * @param amount percentage to saturate, 0-100
     *
     * @return CSS color string, or null if the input is not a valid color
     * @see com.smartgwt.client.util.Colors#desaturate
     * @see com.smartgwt.client.util.Colors#adjust
     */
    public static native String saturate(String color, double amount) /*-{
        var ret = $wnd.isc.Colors.saturate(color, amount);
        return ret;
    }-*/;

	/**
     * Returns a more vivid version of the given color by increasing its chroma (color intensity). Equivalent to
     * <code>adjust(color, {saturation: amount})</code>. <P> The <code>amount</code> is a percentage (0-100) of additional
     * chroma to add, scaled relative to a practical maximum. A gray color (chroma 0) saturated by 50 produces a clearly
     * visible color; 100 gives full vivid saturation. <P> For multi-axis adjustments, use {@link
     * com.smartgwt.client.util.Colors#adjust adjust()} directly.
     * @param color any valid CSS color string or structured color object
     * @param amount percentage to saturate, 0-100
     * @param outputFormat output format; defaults to the detected format of the     input color (hex for named colors)
     *
     * @return CSS color string, or null if the input is not a valid color
     * @see com.smartgwt.client.util.Colors#desaturate
     * @see com.smartgwt.client.util.Colors#adjust
     */
    public static native String saturate(String color, double amount, ColorFormat outputFormat) /*-{
        var ret = $wnd.isc.Colors.saturate(color, amount, outputFormat == null ? null : outputFormat.@com.smartgwt.client.types.ColorFormat::getValue()());
        return ret;
    }-*/;
	

	/**
     * Generates a set of harmonious seed colors from a single primary. Unlike the lower-level harmony methods ({@link
     * com.smartgwt.client.util.Colors#triad triad()}, {@link com.smartgwt.client.util.Colors#tetrad tetrad()}, etc.) which
     * return raw CSS strings at fixed hue rotations, <code>scheme()</code> returns a structured object with semantic key names
     * and applies chroma/lightness adjustments so that secondary and tertiary colors feel subordinate to the primary - a
     * requirement for professional UI themes. <P> The returned object always contains a <code>primary</code> Color plus one or
     * more supporting keys depending on the scheme type. It also includes auto-generated <code>neutral</code> (very low chroma
     * at the primary's hue) and <code>error</code> (red variant) keys. Each seed can be passed to {@link
     * com.smartgwt.client.util.Colors#palette palette()} to generate a full tonal ramp.
     * @param color the primary seed color
     *
     * @return a map with <code>primary</code>, <code>secondary</code>,     <code>tertiary</code> (where applicable),
     * <code>neutral</code>, and     <code>error</code> keys, each a {@link com.smartgwt.client.util.Color} object
     * @see com.smartgwt.client.util.Colors#palette
     * @see com.smartgwt.client.util.Colors#autoContrast
     */
    public static native Map scheme(String color) /*-{
        var ret = $wnd.isc.Colors.scheme(color);
        return @com.smartgwt.client.util.JSOHelper::convertToMap(Lcom/google/gwt/core/client/JavaScriptObject;)(ret);
    }-*/;

	/**
     * Generates a set of harmonious seed colors from a single primary. Unlike the lower-level harmony methods ({@link
     * com.smartgwt.client.util.Colors#triad triad()}, {@link com.smartgwt.client.util.Colors#tetrad tetrad()}, etc.) which
     * return raw CSS strings at fixed hue rotations, <code>scheme()</code> returns a structured object with semantic key names
     * and applies chroma/lightness adjustments so that secondary and tertiary colors feel subordinate to the primary - a
     * requirement for professional UI themes. <P> The returned object always contains a <code>primary</code> Color plus one or
     * more supporting keys depending on the scheme type. It also includes auto-generated <code>neutral</code> (very low chroma
     * at the primary's hue) and <code>error</code> (red variant) keys. Each seed can be passed to {@link
     * com.smartgwt.client.util.Colors#palette palette()} to generate a full tonal ramp.
     * @param color the primary seed color
     *
     * @return a map with <code>primary</code>, <code>secondary</code>,     <code>tertiary</code> (where applicable),
     * <code>neutral</code>, and     <code>error</code> keys, each a {@link com.smartgwt.client.util.Color} object
     * @see com.smartgwt.client.util.Colors#palette
     * @see com.smartgwt.client.util.Colors#autoContrast
     */
    public static native Map scheme(Color color) /*-{
        var ret = $wnd.isc.Colors.scheme(color.@com.smartgwt.client.core.DataClass::getJsObj()());
        return @com.smartgwt.client.util.JSOHelper::convertToMap(Lcom/google/gwt/core/client/JavaScriptObject;)(ret);
    }-*/;

	/**
     * Generates a set of harmonious seed colors from a single primary. Unlike the lower-level harmony methods ({@link
     * com.smartgwt.client.util.Colors#triad triad()}, {@link com.smartgwt.client.util.Colors#tetrad tetrad()}, etc.) which
     * return raw CSS strings at fixed hue rotations, <code>scheme()</code> returns a structured object with semantic key names
     * and applies chroma/lightness adjustments so that secondary and tertiary colors feel subordinate to the primary - a
     * requirement for professional UI themes. <P> The returned object always contains a <code>primary</code> Color plus one or
     * more supporting keys depending on the scheme type. It also includes auto-generated <code>neutral</code> (very low chroma
     * at the primary's hue) and <code>error</code> (red variant) keys. Each seed can be passed to {@link
     * com.smartgwt.client.util.Colors#palette palette()} to generate a full tonal ramp.
     * @param color the primary seed color
     * @param type scheme type: <code>"complementary"</code>,     <code>"analogous"</code>, <code>"triadic"</code>,    
     * <code>"split-complementary"</code> (default), <code>"tetradic"</code>, or     <code>"monochromatic"</code>
     *
     * @return a map with <code>primary</code>, <code>secondary</code>,     <code>tertiary</code> (where applicable),
     * <code>neutral</code>, and     <code>error</code> keys, each a {@link com.smartgwt.client.util.Color} object
     * @see com.smartgwt.client.util.Colors#palette
     * @see com.smartgwt.client.util.Colors#autoContrast
     */
    public static native Map scheme(String color, String type) /*-{
        var ret = $wnd.isc.Colors.scheme(color, type);
        return @com.smartgwt.client.util.JSOHelper::convertToMap(Lcom/google/gwt/core/client/JavaScriptObject;)(ret);
    }-*/;

	/**
     * Generates a set of harmonious seed colors from a single primary. Unlike the lower-level harmony methods ({@link
     * com.smartgwt.client.util.Colors#triad triad()}, {@link com.smartgwt.client.util.Colors#tetrad tetrad()}, etc.) which
     * return raw CSS strings at fixed hue rotations, <code>scheme()</code> returns a structured object with semantic key names
     * and applies chroma/lightness adjustments so that secondary and tertiary colors feel subordinate to the primary - a
     * requirement for professional UI themes. <P> The returned object always contains a <code>primary</code> Color plus one or
     * more supporting keys depending on the scheme type. It also includes auto-generated <code>neutral</code> (very low chroma
     * at the primary's hue) and <code>error</code> (red variant) keys. Each seed can be passed to {@link
     * com.smartgwt.client.util.Colors#palette palette()} to generate a full tonal ramp.
     * @param color the primary seed color
     * @param type scheme type: <code>"complementary"</code>,     <code>"analogous"</code>, <code>"triadic"</code>,    
     * <code>"split-complementary"</code> (default), <code>"tetradic"</code>, or     <code>"monochromatic"</code>
     *
     * @return a map with <code>primary</code>, <code>secondary</code>,     <code>tertiary</code> (where applicable),
     * <code>neutral</code>, and     <code>error</code> keys, each a {@link com.smartgwt.client.util.Color} object
     * @see com.smartgwt.client.util.Colors#palette
     * @see com.smartgwt.client.util.Colors#autoContrast
     */
    public static native Map scheme(Color color, String type) /*-{
        var ret = $wnd.isc.Colors.scheme(color.@com.smartgwt.client.core.DataClass::getJsObj()(), type);
        return @com.smartgwt.client.util.JSOHelper::convertToMap(Lcom/google/gwt/core/client/JavaScriptObject;)(ret);
    }-*/;


	/**
     * Returns a new color string with the alpha (opacity) component replaced. The output format matches the input format when
     * possible; for named colors, hex is used. <P> Useful for deriving semi-transparent variants of a color without converting
     * it to a different format.
     * @param color any valid CSS color string or structured color object
     * @param alpha new alpha value, 0.0 (transparent) to 1.0 (opaque)
     *
     * @return CSS color string with the new alpha, or null if invalid
     */
    public static native String setAlpha(String color, double alpha) /*-{
        var ret = $wnd.isc.Colors.setAlpha(color, alpha);
        return ret;
    }-*/;

	/**
     * Returns a new color string with the alpha (opacity) component replaced. The output format matches the input format when
     * possible; for named colors, hex is used. <P> Useful for deriving semi-transparent variants of a color without converting
     * it to a different format.
     * @param color any valid CSS color string or structured color object
     * @param alpha new alpha value, 0.0 (transparent) to 1.0 (opaque)
     * @param outputFormat optional output format; defaults to the detected format     of the input color
     *
     * @return CSS color string with the new alpha, or null if invalid
     */
    public static native String setAlpha(String color, double alpha, ColorFormat outputFormat) /*-{
        var ret = $wnd.isc.Colors.setAlpha(color, alpha, outputFormat == null ? null : outputFormat.@com.smartgwt.client.types.ColorFormat::getValue()());
        return ret;
    }-*/;
	

	/**
     * Rotates the hue of a color by the given number of degrees (in oklch space). Positive values rotate clockwise, negative
     * counter-clockwise. This is a convenience wrapper around {@link com.smartgwt.client.util.Colors#adjust adjust(color,
     * {hue: degrees})}.
     * @param color any valid CSS color string or structured color object
     * @param degrees signed rotation in degrees (e.g. 90, -45, 180)
     *
     * @return CSS color string, or null if the input is not a valid color
     * @see com.smartgwt.client.util.Colors#adjust
     * @see com.smartgwt.client.util.Colors#complement
     */
    public static native String spin(String color, double degrees) /*-{
        var ret = $wnd.isc.Colors.spin(color, degrees);
        return ret;
    }-*/;

	/**
     * Rotates the hue of a color by the given number of degrees (in oklch space). Positive values rotate clockwise, negative
     * counter-clockwise. This is a convenience wrapper around {@link com.smartgwt.client.util.Colors#adjust adjust(color,
     * {hue: degrees})}.
     * @param color any valid CSS color string or structured color object
     * @param degrees signed rotation in degrees (e.g. 90, -45, 180)
     * @param outputFormat output format; defaults to the detected format of the     input color (hex for named colors)
     *
     * @return CSS color string, or null if the input is not a valid color
     * @see com.smartgwt.client.util.Colors#adjust
     * @see com.smartgwt.client.util.Colors#complement
     */
    public static native String spin(String color, double degrees, ColorFormat outputFormat) /*-{
        var ret = $wnd.isc.Colors.spin(color, degrees, outputFormat == null ? null : outputFormat.@com.smartgwt.client.types.ColorFormat::getValue()());
        return ret;
    }-*/;
	

	/**
     * Returns three colors: the original plus two split-complement accents (hue +150 and +210 degrees - flanking the
     * complement rather than hitting it directly). Produces a more nuanced palette than a straight complementary pair.
     * @param color base color
     *
     * @return three CSS color strings
     */
    public static native String[] splitComplement(String color) /*-{
        var ret = $wnd.isc.Colors.splitComplement(color);
        if(ret == null) return null;
        return @com.smartgwt.client.util.ConvertTo::arrayOfString(Lcom/google/gwt/core/client/JavaScriptObject;)(ret);
    }-*/;

	/**
     * Returns three colors: the original plus two split-complement accents (hue +150 and +210 degrees - flanking the
     * complement rather than hitting it directly). Produces a more nuanced palette than a straight complementary pair.
     * @param color base color
     *
     * @return three CSS color strings
     */
    public static native String[] splitComplement(Color color) /*-{
        var ret = $wnd.isc.Colors.splitComplement(color.@com.smartgwt.client.core.DataClass::getJsObj()());
        if(ret == null) return null;
        return @com.smartgwt.client.util.ConvertTo::arrayOfString(Lcom/google/gwt/core/client/JavaScriptObject;)(ret);
    }-*/;

	/**
     * Returns three colors: the original plus two split-complement accents (hue +150 and +210 degrees - flanking the
     * complement rather than hitting it directly). Produces a more nuanced palette than a straight complementary pair.
     * @param color base color
     * @param outputFormat output format; defaults to input format
     *
     * @return three CSS color strings
     */
    public static native String[] splitComplement(String color, ColorFormat outputFormat) /*-{
        var ret = $wnd.isc.Colors.splitComplement(color, outputFormat == null ? null : outputFormat.@com.smartgwt.client.types.ColorFormat::getValue()());
        if(ret == null) return null;
        return @com.smartgwt.client.util.ConvertTo::arrayOfString(Lcom/google/gwt/core/client/JavaScriptObject;)(ret);
    }-*/;

	/**
     * Returns three colors: the original plus two split-complement accents (hue +150 and +210 degrees - flanking the
     * complement rather than hitting it directly). Produces a more nuanced palette than a straight complementary pair.
     * @param color base color
     * @param outputFormat output format; defaults to input format
     *
     * @return three CSS color strings
     */
    public static native String[] splitComplement(Color color, ColorFormat outputFormat) /*-{
        var ret = $wnd.isc.Colors.splitComplement(color.@com.smartgwt.client.core.DataClass::getJsObj()(), outputFormat == null ? null : outputFormat.@com.smartgwt.client.types.ColorFormat::getValue()());
        if(ret == null) return null;
        return @com.smartgwt.client.util.ConvertTo::arrayOfString(Lcom/google/gwt/core/client/JavaScriptObject;)(ret);
    }-*/;


	/**
     * Returns four colors with hues spaced 90 degrees apart (square scheme). The first element is the original color, then
     * +90, +180, +270 degrees.
     * @param color base color
     *
     * @return four CSS color strings
     */
    public static native String[] tetrad(String color) /*-{
        var ret = $wnd.isc.Colors.tetrad(color);
        if(ret == null) return null;
        return @com.smartgwt.client.util.ConvertTo::arrayOfString(Lcom/google/gwt/core/client/JavaScriptObject;)(ret);
    }-*/;

	/**
     * Returns four colors with hues spaced 90 degrees apart (square scheme). The first element is the original color, then
     * +90, +180, +270 degrees.
     * @param color base color
     *
     * @return four CSS color strings
     */
    public static native String[] tetrad(Color color) /*-{
        var ret = $wnd.isc.Colors.tetrad(color.@com.smartgwt.client.core.DataClass::getJsObj()());
        if(ret == null) return null;
        return @com.smartgwt.client.util.ConvertTo::arrayOfString(Lcom/google/gwt/core/client/JavaScriptObject;)(ret);
    }-*/;

	/**
     * Returns four colors with hues spaced 90 degrees apart (square scheme). The first element is the original color, then
     * +90, +180, +270 degrees.
     * @param color base color
     * @param outputFormat output format; defaults to input format
     *
     * @return four CSS color strings
     */
    public static native String[] tetrad(String color, ColorFormat outputFormat) /*-{
        var ret = $wnd.isc.Colors.tetrad(color, outputFormat == null ? null : outputFormat.@com.smartgwt.client.types.ColorFormat::getValue()());
        if(ret == null) return null;
        return @com.smartgwt.client.util.ConvertTo::arrayOfString(Lcom/google/gwt/core/client/JavaScriptObject;)(ret);
    }-*/;

	/**
     * Returns four colors with hues spaced 90 degrees apart (square scheme). The first element is the original color, then
     * +90, +180, +270 degrees.
     * @param color base color
     * @param outputFormat output format; defaults to input format
     *
     * @return four CSS color strings
     */
    public static native String[] tetrad(Color color, ColorFormat outputFormat) /*-{
        var ret = $wnd.isc.Colors.tetrad(color.@com.smartgwt.client.core.DataClass::getJsObj()(), outputFormat == null ? null : outputFormat.@com.smartgwt.client.types.ColorFormat::getValue()());
        if(ret == null) return null;
        return @com.smartgwt.client.util.ConvertTo::arrayOfString(Lcom/google/gwt/core/client/JavaScriptObject;)(ret);
    }-*/;


	/**
     * Returns the three triadic colors (hues spaced 120 degrees apart). The first element is the original color, the second is
     * +120 degrees, the third is +240 degrees.
     * @param color base color
     *
     * @return three CSS color strings
     */
    public static native String[] triad(String color) /*-{
        var ret = $wnd.isc.Colors.triad(color);
        if(ret == null) return null;
        return @com.smartgwt.client.util.ConvertTo::arrayOfString(Lcom/google/gwt/core/client/JavaScriptObject;)(ret);
    }-*/;

	/**
     * Returns the three triadic colors (hues spaced 120 degrees apart). The first element is the original color, the second is
     * +120 degrees, the third is +240 degrees.
     * @param color base color
     *
     * @return three CSS color strings
     */
    public static native String[] triad(Color color) /*-{
        var ret = $wnd.isc.Colors.triad(color.@com.smartgwt.client.core.DataClass::getJsObj()());
        if(ret == null) return null;
        return @com.smartgwt.client.util.ConvertTo::arrayOfString(Lcom/google/gwt/core/client/JavaScriptObject;)(ret);
    }-*/;

	/**
     * Returns the three triadic colors (hues spaced 120 degrees apart). The first element is the original color, the second is
     * +120 degrees, the third is +240 degrees.
     * @param color base color
     * @param outputFormat output format; defaults to input format
     *
     * @return three CSS color strings
     */
    public static native String[] triad(String color, ColorFormat outputFormat) /*-{
        var ret = $wnd.isc.Colors.triad(color, outputFormat == null ? null : outputFormat.@com.smartgwt.client.types.ColorFormat::getValue()());
        if(ret == null) return null;
        return @com.smartgwt.client.util.ConvertTo::arrayOfString(Lcom/google/gwt/core/client/JavaScriptObject;)(ret);
    }-*/;

	/**
     * Returns the three triadic colors (hues spaced 120 degrees apart). The first element is the original color, the second is
     * +120 degrees, the third is +240 degrees.
     * @param color base color
     * @param outputFormat output format; defaults to input format
     *
     * @return three CSS color strings
     */
    public static native String[] triad(Color color, ColorFormat outputFormat) /*-{
        var ret = $wnd.isc.Colors.triad(color.@com.smartgwt.client.core.DataClass::getJsObj()(), outputFormat == null ? null : outputFormat.@com.smartgwt.client.types.ColorFormat::getValue()());
        if(ret == null) return null;
        return @com.smartgwt.client.util.ConvertTo::arrayOfString(Lcom/google/gwt/core/client/JavaScriptObject;)(ret);
    }-*/;


    // ***********************************************************



/**
 * Hand-written overloads for Colors methods that take two color parameters.
 * Auto-generation can only vary the first parameter's type, so these methods
 * need manual (String, String) + (Color, Color) pairs.
 */

    // ---------------------------------------------------------------
    // colorScale
    // ---------------------------------------------------------------

    /**
     * Generates an array of evenly-spaced colors between two endpoints,
     * interpolated in oklch by default.  Use the 5-parameter overload
     * to choose a different interpolation space.
     *
     * @param color1 start color
     * @param color2 end color
     * @param steps  number of colors to produce (minimum 2)
     * @return CSS color strings, or null if either input is invalid
     */
    public static native String[] colorScale(String color1, String color2,
            int steps) /*-{
        var ret = $wnd.isc.Colors.colorScale(color1, color2, steps);
        if (ret == null) return null;
        return @com.smartgwt.client.util.ConvertTo::arrayOfString(Lcom/google/gwt/core/client/JavaScriptObject;)(ret);
    }-*/;

    /**
     * Generates an array of evenly-spaced colors between two endpoints,
     * interpolated in the oklch color space for perceptual uniformity.
     *
     * @param color1 start color
     * @param color2 end color
     * @param steps  number of colors to produce (minimum 2)
     * @param format output format; defaults to the detected format of
     *               {@code color1}
     * @return CSS color strings, or null if either input is invalid
     */
    public static native String[] colorScale(String color1, String color2,
            int steps, ColorFormat format) /*-{
        var ret = $wnd.isc.Colors.colorScale(color1, color2, steps,
            format == null ? null :
            format.@com.smartgwt.client.types.ColorFormat::getValue()());
        if (ret == null) return null;
        return @com.smartgwt.client.util.ConvertTo::arrayOfString(Lcom/google/gwt/core/client/JavaScriptObject;)(ret);
    }-*/;

    /**
     * Generates an array of evenly-spaced colors between two
     * {@link Color} endpoints, interpolated in the oklch color space
     * for perceptual uniformity.
     *
     * @param color1 start color
     * @param color2 end color
     * @param steps  number of colors to produce (minimum 2)
     * @return CSS color strings, or null if either input is invalid
     */
    public static native String[] colorScale(Color color1, Color color2,
            int steps) /*-{
        var ret = $wnd.isc.Colors.colorScale(
            color1.@com.smartgwt.client.core.DataClass::getJsObj()(),
            color2.@com.smartgwt.client.core.DataClass::getJsObj()(),
            steps);
        if (ret == null) return null;
        return @com.smartgwt.client.util.ConvertTo::arrayOfString(Lcom/google/gwt/core/client/JavaScriptObject;)(ret);
    }-*/;

    /**
     * Generates an array of evenly-spaced colors between two
     * {@link Color} endpoints, interpolated in the oklch color space
     * for perceptual uniformity.
     *
     * @param color1 start color
     * @param color2 end color
     * @param steps  number of colors to produce (minimum 2)
     * @param format output format; defaults to the detected format of
     *               {@code color1}
     * @return CSS color strings, or null if either input is invalid
     */
    public static native String[] colorScale(Color color1, Color color2,
            int steps, ColorFormat format) /*-{
        var ret = $wnd.isc.Colors.colorScale(
            color1.@com.smartgwt.client.core.DataClass::getJsObj()(),
            color2.@com.smartgwt.client.core.DataClass::getJsObj()(),
            steps,
            format == null ? null :
            format.@com.smartgwt.client.types.ColorFormat::getValue()());
        if (ret == null) return null;
        return @com.smartgwt.client.util.ConvertTo::arrayOfString(Lcom/google/gwt/core/client/JavaScriptObject;)(ret);
    }-*/;

    /**
     * Generates an array of evenly-spaced colors between two
     * endpoints, interpolated in the specified color space.
     *
     * @param color1 start color
     * @param color2 end color
     * @param steps  number of colors to produce (minimum 2)
     * @param format output format; defaults to the detected format of
     *               {@code color1}
     * @param space  color space for interpolation: oklch (default),
     *               hsl, or rgb/hex (both mean linear RGB)
     * @return CSS color strings, or null if either input is invalid
     */
    public static native String[] colorScale(String color1, String color2,
            int steps, ColorFormat format, ColorFormat space) /*-{
        var ret = $wnd.isc.Colors.colorScale(color1, color2, steps,
            format == null ? null :
            format.@com.smartgwt.client.types.ColorFormat::getValue()(),
            space == null ? null :
            space.@com.smartgwt.client.types.ColorFormat::getValue()());
        if (ret == null) return null;
        return @com.smartgwt.client.util.ConvertTo::arrayOfString(Lcom/google/gwt/core/client/JavaScriptObject;)(ret);
    }-*/;

    /**
     * Generates an array of evenly-spaced colors between two
     * {@link Color} endpoints, interpolated in the specified color
     * space.
     *
     * @param color1 start color
     * @param color2 end color
     * @param steps  number of colors to produce (minimum 2)
     * @param format output format; defaults to the detected format of
     *               {@code color1}
     * @param space  color space for interpolation: oklch (default),
     *               hsl, or rgb/hex (both mean linear RGB)
     * @return CSS color strings, or null if either input is invalid
     */
    public static native String[] colorScale(Color color1, Color color2,
            int steps, ColorFormat format, ColorFormat space) /*-{
        var ret = $wnd.isc.Colors.colorScale(
            color1.@com.smartgwt.client.core.DataClass::getJsObj()(),
            color2.@com.smartgwt.client.core.DataClass::getJsObj()(),
            steps,
            format == null ? null :
            format.@com.smartgwt.client.types.ColorFormat::getValue()(),
            space == null ? null :
            space.@com.smartgwt.client.types.ColorFormat::getValue()());
        if (ret == null) return null;
        return @com.smartgwt.client.util.ConvertTo::arrayOfString(Lcom/google/gwt/core/client/JavaScriptObject;)(ret);
    }-*/;

    // ---------------------------------------------------------------
    // flatten
    // ---------------------------------------------------------------

    /**
     * Returns an opaque color visually equivalent to the given
     * semi-transparent color composited over a background (default
     * white).  If already fully opaque, returns unchanged.
     *
     * @param color a semi-transparent color to flatten
     * @return opaque CSS color string, or null if invalid
     */
    public static native String flatten(String color) /*-{
        var ret = $wnd.isc.Colors.flatten(color);
        return ret;
    }-*/;

    /**
     * Returns an opaque color visually equivalent to the given
     * semi-transparent {@link Color} composited over a background
     * (default white).  If already fully opaque, returns unchanged.
     *
     * @param color a semi-transparent color to flatten
     * @return opaque CSS color string, or null if invalid
     */
    public static native String flatten(Color color) /*-{
        var ret = $wnd.isc.Colors.flatten(
            color.@com.smartgwt.client.core.DataClass::getJsObj()());
        return ret;
    }-*/;

    /**
     * Flattens a semi-transparent color against a background.
     *
     * @param color      a semi-transparent color to flatten
     * @param background background to composite against
     * @return opaque CSS color string, or null if invalid
     */
    public static String flatten(String color, String background) {
        return flatten(color, background, null);
    }

    /**
     * Flattens a semi-transparent color against a background,
     * returning the result in the specified format.
     *
     * @param color        a semi-transparent color to flatten
     * @param background   background to composite against
     * @param outputFormat output format; defaults to the detected
     *                     format of the input color
     * @return opaque CSS color string, or null if invalid
     */
    public static native String flatten(String color, String background,
            ColorFormat outputFormat) /*-{
        var ret = $wnd.isc.Colors.flatten(color, background,
            outputFormat == null ? null :
            outputFormat.@com.smartgwt.client.types.ColorFormat::getValue()());
        return ret;
    }-*/;

    /**
     * Flattens a semi-transparent {@link Color} against a background.
     *
     * @param color      a semi-transparent color to flatten
     * @param background background to composite against
     * @return opaque CSS color string, or null if invalid
     */
    public static String flatten(Color color, Color background) {
        return flatten(color, background, null);
    }

    /**
     * Flattens a semi-transparent {@link Color} against a background,
     * returning the result in the specified format.
     *
     * @param color        a semi-transparent color to flatten
     * @param background   background to composite against
     * @param outputFormat output format; defaults to the detected
     *                     format of the input color
     * @return opaque CSS color string, or null if invalid
     */
    public static native String flatten(Color color, Color background,
            ColorFormat outputFormat) /*-{
        var ret = $wnd.isc.Colors.flatten(
            color.@com.smartgwt.client.core.DataClass::getJsObj()(),
            background.@com.smartgwt.client.core.DataClass::getJsObj()(),
            outputFormat == null ? null :
            outputFormat.@com.smartgwt.client.types.ColorFormat::getValue()());
        return ret;
    }-*/;

    // ---------------------------------------------------------------
    // contrast
    // ---------------------------------------------------------------

    /**
     * Returns the approximate perceptual contrast ratio between two
     * colors, based on oklch lightness.  A ratio of at least 4.5 is
     * recommended for WCAG AA, 7.0 for AAA.  Returns null if either
     * color is invalid.
     *
     * @param color1 first color
     * @param color2 second color
     * @return contrast ratio (&gt;= 1.0), or null
     */
    public static native Double contrast(String color1, String color2) /*-{
        var ret = $wnd.isc.Colors.contrast(color1, color2);
        if (ret == null) return null;
        return @com.smartgwt.client.util.JSOHelper::toDouble(D)(ret);
    }-*/;

    /**
     * Returns the approximate perceptual contrast ratio between two
     * {@link Color} objects, based on oklch lightness.  A ratio of at
     * least 4.5 is recommended for WCAG AA, 7.0 for AAA.  Returns
     * null if either color is invalid.
     *
     * @param color1 first color
     * @param color2 second color
     * @return contrast ratio (&gt;= 1.0), or null
     */
    public static native Double contrast(Color color1, Color color2) /*-{
        var ret = $wnd.isc.Colors.contrast(
            color1.@com.smartgwt.client.core.DataClass::getJsObj()(),
            color2.@com.smartgwt.client.core.DataClass::getJsObj()());
        if (ret == null) return null;
        return @com.smartgwt.client.util.JSOHelper::toDouble(D)(ret);
    }-*/;

    // ---------------------------------------------------------------
    // distance
    // ---------------------------------------------------------------

    /**
     * Returns a number indicating how different two colors look to the
     * human eye.  0 means identical; larger values mean more visible
     * difference.  Uses oklab (the Cartesian form of oklch) so that
     * equal numeric distances correspond to equal perceived differences.
     * Returns null if either color is invalid.
     *
     * @param color1 first color
     * @param color2 second color
     * @return perceptual distance (&gt;= 0), or null
     */
    public static native Double distance(String color1, String color2) /*-{
        var ret = $wnd.isc.Colors.distance(color1, color2);
        if (ret == null) return null;
        return @com.smartgwt.client.util.JSOHelper::toDouble(D)(ret);
    }-*/;

    /**
     * Returns a number indicating how different two {@link Color}
     * objects look to the human eye.  0 means identical; larger values
     * mean more visible difference.  Uses oklab so that equal numeric
     * distances correspond to equal perceived differences.  Returns
     * null if either color is invalid.
     *
     * @param color1 first color
     * @param color2 second color
     * @return perceptual distance (&gt;= 0), or null
     */
    public static native Double distance(Color color1, Color color2) /*-{
        var ret = $wnd.isc.Colors.distance(
            color1.@com.smartgwt.client.core.DataClass::getJsObj()(),
            color2.@com.smartgwt.client.core.DataClass::getJsObj()());
        if (ret == null) return null;
        return @com.smartgwt.client.util.JSOHelper::toDouble(D)(ret);
    }-*/;

    // ---------------------------------------------------------------
    // equals
    // ---------------------------------------------------------------

    /**
     * Returns true if two color values represent the same color (same
     * R, G, B, and alpha), regardless of input format.
     *
     * @param color1 first color
     * @param color2 second color
     * @return true if identical, false otherwise, null if either invalid
     */
    public static native Boolean equals(String color1, String color2) /*-{
        var ret = $wnd.isc.Colors.equals(color1, color2);
        if (ret == null) return null;
        return @com.smartgwt.client.util.JSOHelper::toBoolean(Z)(ret);
    }-*/;

    /**
     * Returns true if two {@link Color} objects represent the same
     * color (same R, G, B, and alpha).
     *
     * @param color1 first color
     * @param color2 second color
     * @return true if identical, false otherwise, null if either invalid
     */
    public static native Boolean equals(Color color1, Color color2) /*-{
        var ret = $wnd.isc.Colors.equals(
            color1.@com.smartgwt.client.core.DataClass::getJsObj()(),
            color2.@com.smartgwt.client.core.DataClass::getJsObj()());
        if (ret == null) return null;
        return @com.smartgwt.client.util.JSOHelper::toBoolean(Z)(ret);
    }-*/;

    // ---------------------------------------------------------------
    // mix
    // ---------------------------------------------------------------

    /**
     * Blends two colors in the oklch color space, producing a single
     * result.  Equivalent to calling
     * {@link #mix(String, String, Double, ColorFormat)} with default
     * ratio (0.5) and default format.
     *
     * @param color1 first color
     * @param color2 second color
     * @return CSS color string, or null if either input is invalid
     */
    public static native String mix(String color1, String color2) /*-{
        var ret = $wnd.isc.Colors.mix(color1, color2);
        return ret;
    }-*/;

    /**
     * Blends two colors in the oklch color space at the given ratio.
     *
     * @param color1 first color
     * @param color2 second color
     * @param ratio  blend ratio, 0.0 (all color1) to 1.0 (all color2);
     *               defaults to 0.5
     * @return CSS color string, or null if either input is invalid
     */
    public static String mix(String color1, String color2, Double ratio) {
        return mix(color1, color2, ratio, null);
    }

    /**
     * Blends two colors in the oklch color space at the given ratio,
     * returning the result in the specified format.
     *
     * @param color1       first color
     * @param color2       second color
     * @param ratio        blend ratio, 0.0 (all color1) to 1.0
     *                     (all color2); defaults to 0.5
     * @param outputFormat output format; defaults to the detected
     *                     format of {@code color1}
     * @return CSS color string, or null if either input is invalid
     */
    public static native String mix(String color1, String color2,
            Double ratio, ColorFormat outputFormat) /*-{
        var ret = $wnd.isc.Colors.mix(color1, color2,
            ratio == null ? null :
            ratio.@java.lang.Double::doubleValue()(),
            outputFormat == null ? null :
            outputFormat.@com.smartgwt.client.types.ColorFormat::getValue()());
        return ret;
    }-*/;

    /**
     * Blends two {@link Color} objects in the oklch color space.
     * Equivalent to calling
     * {@link #mix(Color, Color, Double, ColorFormat)} with default
     * ratio (0.5) and default format.
     *
     * @param color1 first color
     * @param color2 second color
     * @return CSS color string, or null if either input is invalid
     */
    public static native String mix(Color color1, Color color2) /*-{
        var ret = $wnd.isc.Colors.mix(
            color1.@com.smartgwt.client.core.DataClass::getJsObj()(),
            color2.@com.smartgwt.client.core.DataClass::getJsObj()());
        return ret;
    }-*/;

    /**
     * Blends two {@link Color} objects in the oklch color space at
     * the given ratio.
     *
     * @param color1 first color
     * @param color2 second color
     * @param ratio  blend ratio, 0.0 (all color1) to 1.0 (all color2);
     *               defaults to 0.5
     * @return CSS color string, or null if either input is invalid
     */
    public static String mix(Color color1, Color color2, Double ratio) {
        return mix(color1, color2, ratio, null);
    }

    /**
     * Blends two {@link Color} objects in the oklch color space at
     * the given ratio, returning the result in the specified format.
     *
     * @param color1       first color
     * @param color2       second color
     * @param ratio        blend ratio, 0.0 (all color1) to 1.0
     *                     (all color2); defaults to 0.5
     * @param outputFormat output format; defaults to the detected
     *                     format of {@code color1}
     * @return CSS color string, or null if either input is invalid
     */
    public static native String mix(Color color1, Color color2,
            Double ratio, ColorFormat outputFormat) /*-{
        var ret = $wnd.isc.Colors.mix(
            color1.@com.smartgwt.client.core.DataClass::getJsObj()(),
            color2.@com.smartgwt.client.core.DataClass::getJsObj()(),
            ratio == null ? null :
            ratio.@java.lang.Double::doubleValue()(),
            outputFormat == null ? null :
            outputFormat.@com.smartgwt.client.types.ColorFormat::getValue()());
        return ret;
    }-*/;

}
