@lxweb/color v0.5.0

Introduction :

Color allows to easily handle color manipulation with access to each aspect of it (hue, saturation, light, alpha). For exemple, you can dynamically set tint, tone and shade of a color by changing only the saturation or light properties.

A main Color can be a reference, linked by a other Color with some offset in saturation for exemple. That allows you to create a dynamic color theme through a set of linked Color which will adapt to any change from the main one.

In short :

A simple HSL model :

const {hue, saturation, light, alpha} = {360, 90, 70, 100} // A soft red

// Named properties :
const mainColor = new Color({hue, saturation, light, alpha});
// Or direct values :
const mainColor = new Color(hue, saturation, light, alpha);

References to link Color through a dynamic theme :

const darkOffsets = { light: -30 };
const darkMainColor = new Color({ ref: mainColor, offsets: darkOffsets });

// mainColor as reference, with a -30 offset in light :
darMainColor.toHsl(); // "hsl(360, 90%, 40%)"

mainColor.hue = 30; // If the main color change,
// All dependant Color will change accordingly :
darkMainColor.toHsl(); // "hsl(30, 90%, 40%)"

Simple offset or callback to fine-tune the relation between colors :

const offsets = {
	saturation: sat => sat / 2,
	alpha: -30,
};
const shadowColor = new Color(mainColor, alpha);
// Callback give access to the reference property value
shadowColor.toHsl(); // "hsla(30, 45%, 30%, 70%)"

Use the .set() method to update a parent color with a color input value :

// 1 : Offer custom colors to your users :
const colorInput = document.querySelector("input[type='color']");

colorInput.addEventListener("change", event => {
	const userColor = event.currentTarget.value;

	// 2 : Color accept CSS color string to initialize directly from inputs :
	mainColor.set(userColor); // Update your main color with .set()

	// 3 : Update your CSS with the new values :
	document.body.style.setProperty("--main-color", mainColor.toHsl());
	document.body.style.setProperty("--secondary-color", secondaryColor.toHsl());
	document.body.style.setProperty("--background-color", backgroundColor.toHsl());
});

For those who aren't familiar with color theory :

Color properties :

Colors can be describe by 3 properties : Hue, intensity and value.

Color value :

There are 3 ways to change the value of a color, Tint, tone and shade :

Color harmonies :

Harmonies are the combination of colors in an aesthetically pleasing way. Here are 7 color schemes to help you choose colors that go well together, to make your design look natural and professional.

The HSL solution :

The HSL color system handle color with 3 properties : Hue, Saturation and Light, based on colors properties from color theory (instead of a thechnical view like the RGB system), which make color manipulation very easy. This is how designer think about color, so it's important that developers can apply this vision easily.

The Color object :

Create a Color :

const hue = 360; // red
const saturation = 90;
const light = 70;
const alpha = 100;

new Color(hue, saturation, light, alpha);

const properties = {
	hue: 240,
	saturation: 100,
	light: 30,
	alpha: 80,
};
new Color(properties);
new Color({ properties, offsets: {} });

new Color("#ff0000");
new Color("rgb(255, 0, 0)");
new Color("hsl(360, 100, 50)");

new Color();

Default values :

• hue = 0, 0 deg on the color wheel is pure red.
• saturation = 100, 100% : Pure color.
• light = 50, 50% : Pure color (0% is black, 100% is white).
• alpha = 100, 100% : No transparency.

Create a child Color :

An other Color object can be passed as parameter : It will be the reference to keep a dynamic link to its properties.

const mainColor = new Color(360, 90, 70);

// mainColor as reference, with a -30 offset in light :
const darkMainColor = new Color(mainColor, { light: -30 });

darMainColor.toHsl(); // "hsl(360, 90%, 40%)"

The new instance inherit the properties of the reference. Offset properties allows a dynamic shift of the reference value : If the parent Color change, the child inherit the change as well.

mainColor.hue = 30; // If the main color change,
// All dependant Color will change accordingly :
darkMainColor.toHsl(); // "hsl(30, 90%, 40%)"

new Color(ParentColor, { saturation: -30, light: +20 });

new Color({ ref: ParentColor, offsets: { saturation: -30, light: +20 } });

new Color(ParentColor);

Default values :

• hueOffset = 0, No shift from the reference hue.
• saturationOffset = 0, No shift from the reference saturation.
• lightOffset = 0, No shift from the reference light.
• alphaOffset = 0, No shift from the reference alpha.

// Simple offset, added to the reference value :
childColor.saturationOffset = 10;

// Or callback :
childColor.lightOffset = lightRef => lightRef / 2;

childColor.alphaOffset = alphaRef => {
	// take the reference value,
	if (alphaRef > 50) return alphaRef - 20;
	return alphaRef / 2;
	// return a new value.
};

Simple offset or callback to fine-tune the relation between colors.

childColor.saturation = 50; // Set a fixed value on a child Color

A property can be set directly on the child Color. This value will be fixed, independent of the reference value.

Constructor parameters :

• Hue : A number for the color position on the color wheel. It will still work if the number is outside the usual position (between 0 and 360°), or a CSS <angle> string ( deg | turn | rad | grad ), that will determine the hue value.

  For exemple -120 will have the same result as 240 (-120 + 360 = 240 : same position on the wheel).

• CSS color string : A hexadecimal ( "#ff0000" ), RGB ( "rgb(255, 0, 0)" ) or HSL ( "hsl(0, 100, 50)" ) color format that will determine the hue, saturation, light and alpha values.

• Color object : An other Color object can be passed, to be the reference on which this new Color will be based.

  All next parameters become offset to shift from this reference.

• Object : An object with a collection of named properties to easily set any option of the Color object in one go. See the parameter object details section to know more.

  All next parameters will be ignored.

• If the 1st parameter is a hue value : this one have to be a number and will set the saturation value (100 by default : Pure color).
• If the 1st parameter is a Color object : this one have to be a object that will set the offsets values (0 by default for all offsets : No offset).See detailsThe offsets object accepts 4 properties : hue, saturation, light and alpha, that will sets the offset for the corresponding color value (See offsets parameter object ).Each is optionnal, and accept : - A number, which will be add to the parent value to obtain the child value, - Or a callback, which will get the parent value as parameter, and have to return a number to be the child value.
• If the 1st parameter is a CSS color string or a object : this one will be ignored.

• If the 1st parameter is a hue value : this one have to be a number and will set the light value ( 50 by default: Pure color ).
• For all other case : this one will be ignored.

• If the 1st parameter is a hue value : this one have to be a number and will set the alpha value ( 100 by default : No transparency ).
• For all other case : this one will be ignored.

Parameter object details :

General parameter object :

If the 1st parameter is a object, all Color properties can be set in one go :

• Every properties are optionnal.
• If a color property is set both directly ( { hue } ) and in a collection of properties object ( { properties: { hue } } ), the value in the set will take priority and the direct property will be ignored.
• Idem for offsets.
• parentColor is a alias for ref to assign a parent Color. If both are put, parentColor will be ignored.

{
   // Color properties :
   hue : number | <angle> string,
   saturation: number,
   light: number,
   alpha: number,

   // Collection of color properties :
   properties: {
      hue : number | <angle> string,
      saturation: number,
      light: number,
      alpha: number,
   }

   // CSS color string (hexa, rgb or hsl) :
   css: string,

   // Color reference :
   ref: Color,
   parentColor: Color, // Alias

   // Offsets :
   hueOffset : number | (parentHue) => number,
   saturationOffset: number | (parentSaturation) => number,
   lightOffset: number | (parentLight) => number,
   alphaOffset: number | (parentAlpha) => number,

   // Collection of offsets :
   Offsets: {
      hue : number | (parentHue) => number,
      saturation: number | (parentSaturation) => number,
      light: number | (parentLight) => number,
      alpha: number | (parentAlpha) => number,
   }
}

Offsets parameter object :

If the 1st argument is a Color object to set the parent reference, the 2nd argument is a object of offsets :

{
   // Offsets :
   hue : number | (parentHue) => number,
   saturation: number | (parentSaturation) => number,
   light: number | (parentLight) => number,
   alpha: number | (parentAlpha) => number,
}

Properties :

Color properties :

If this value is set on a child Color, the parent hue value will be ignored.

• Getter Color.hue : 0 ⩽ number < 360 .
  • If Color is a child with no own hue value: hue will return the value of the parent with the offset applied.
  • Default value : 0 (red).
• Setter Color.hue = number | css \<angle> string :
  • If null or undefined, assignment will be ignored.
  • No need to format the number between 0 and 360, it will still work outside the usual position.

    For exemple -120 will have the same result as 240 (-120 + 360 = 240 : same position on the wheel).

If this value is set on a child Color, the parent saturation value will be ignored.

• Getter Color.saturation : 0 ⩽ number ⩽ 100 .
  • If Color is a child with no own saturation value, saturation will return the value of the parent with the offset applied.
  • Default value : 100 (pure color).
• Setter Color.saturation = number :
  • Every number below 0 will set the saturation to 0.
  • Every number above 100 will set the saturation to 100.
  • If null or undefined, assignment will be ignored.

If this value is set on a child Color, the parent light value will be ignored.

• Getter Color.light : 0 ⩽ number ⩽ 100 .
  • If Color is a child with no own light value, light will return the value of the parent with the offset applied.
  • Default value : 50 (pure color).
• Setter Color.light = number :
  • Every number below 0 will set the light to 0.
  • Every number above 100 will set the light to 100.
  • If null or undefined, assignment will be ignored.

If this value is set on a child Color, the parent alpha value will be ignored.

• Getter Color.alpha : 0 ⩽ number ⩽ 100 .
  • If Color is a child with no own alpha value, alpha will return the value of the parent with the offset applied.
  • Default value : 100 (no transparency).
• Setter Color.alpha = number :
  • Every number below 0 will set the alpha to 0.
  • Every number above 100 will set the alpha to 100.
  • If null or undefined, assignment will be ignored.

If Color don't have a parent, offset will be ignored.

• Getter Color.hueOffset : number | function.
  • Default value : 0 (no change from parent value).
• Setter Color.hueOffset = number | function.
  • If hueOffset is a number, the hue value will be Parent.hue + Child.hueOffset.
  • If hueOffset is a function, the Parent.hue value will be given as parameter, and the function must return the wanted hue value.
  • If null or undefined, assignment will be ignored.

If Color don't have a parent, offset will be ignored.

• Getter Color.saturationOffset : number | function.
  • Default value : 0 (no change from parent value).
• Setter Color.saturationOffset = number | function.
  • If saturationOffset is a number, the saturation value will be Parent.saturation + Child.saturationOffset.
  • If saturationOffset is a function, the Parent.saturation value will be given as parameter, and the function must return the wanted saturation value.
  • If null or undefined, assignment will be ignored.

If Color don't have a parent, offset will be ignored.

• Getter Color.lightOffset : number | function.
  • Default value : 0 (no change from parent value).
• Setter Color.lightOffset = number | function.
  • If lightOffset is a number, the light value will be Parent.light + Child.lightOffset.
  • If lightOffset is a function, the Parent.light value will be given as parameter, and the function must return the wanted light value.
  • If null or undefined, assignment will be ignored.

If Color don't have a parent, offsets will be ignored.

• Getter Color.alphaOffset : number | function.
  • Default value : 0 (no change from parent value).
• Setter Color.alphaOffset = number | function.
  • If alphaOffset is a number, the alpha value will be Parent.alpha + Child.alphaOffset.
  • If alphaOffset is a function, the Parent.alpha value will be given as parameter, and the function must return the wanted alpha value.
  • If null or undefined, assignment will be ignored.

A Color reference cannot be deleted, only update by a new one.

• Getter Color.ref : Color.
  • Default value : undefined ( no parent Color ).
• Setter Color.ref = Color.
  • If null or undefined, assignment will be ignored.

A Color reference cannot be deleted, only update by a new one.

• Getter Color.parent : Color.
  • Default value : undefined ( no parent Color ).
• Setter Color.parent = Color.
  • If null or undefined, assignment will be ignored.

Methods :

CSS color string export methods :

const mainColor = new Color(360, 90, 70);
mainColor.toHsl(); // "hsl(360, 90%, 70%)"

mainColor.alpha = 50;
mainColor.toHsl(); // "hsla(360, 90%, 70%, 50%)"

const mainColor = new Color(360, 90, 70);
mainColor.toRgb(); // "rgb(247, 110, 110)"

mainColor.alpha = 50;
mainColor.toRgb(); // "rgba(247, 110, 110, 0.5)"

const mainColor = new Color(360, 90, 70);
mainColor.toHex(); // "#f76e6e"

mainColor.alpha = 50;
mainColor.toHex(); // "#f76e6e80"

const color = new Color({
	properties: { hue: 180, light: 35 },
	offsets: { saturation: sat => sat / 2 },
});

color.set(); // No changes.
color.set({ hue: 0 }); // Only the hue property will change.
// All color properties will be set from the CSS string :
color.set("#ff0000"); // The offsets will remain unchanged.

const color = new Color({
	properties: { hue: 180, light: 35 },
	offsets: { saturation: sat => sat / 2 },
});

color.reset(); // Back to default values, no offsets.
// hue property will be 123 :
color.reset({ hue: 123 }); // All other set to default values.
// All color properties will be set from the CSS string :
color.reset("#ff0000"); // The offsets will reset to 0.

const color = new Color({ hue: 180, light: 35 });

color.setColorProperties(); // No changes.
color.setColorProperties({ hue: 123 }); // Only hue will change.

const darkChild = new Color(parent, { saturation: -20, light: -20 });

darkChild.setColorOffsets(); // No changes.
darkChild.setColorOffsets({ alpha: -30 }); // Add a alpha offset.