@phun-ky/moebius
Version:
@phun-ky/moebius is a versatile JavaScript library that automatically generates visually pleasing and customizable color palettes from a given base color. Whether you're building data visualizations, UIs, or design systems, Möbius offers various harmony m
567 lines (561 loc) • 24.8 kB
TypeScript
/**
* MoebiusColor class representing a color with various formats and conversions.
*
* @example
* ```ts
* const mColor = new MoebiusColor('#ff9900')
* ```
*/
declare class MoebiusColor implements MoebiusColorInterface {
color: MoebiusChromaColorInputType;
name: string;
hex: MoebiusColorValueHexType;
rgb: MoebiusColorValueRgbType;
hsl: MoebiusHSLObjectType;
hwb: MoebiusHWBObjectType;
hsv: MoebiusHSVObjectType;
lab: MoebiusLABObjectType;
xyz: MoebiusXYZObjectType;
lch: MoebiusLCHObjectType;
oklch: MoebiusLCHObjectType;
hsi: MoebiusHSIObjectType;
oklab: MoebiusLABObjectType;
cmyk: MoebiusCMYKObjectType;
rgbFloat: MoebiusRGBObjectType;
hslFloat: MoebiusHSLObjectType;
/**
* Creates an instance of MoebiusColor.
* @param {MoebiusChromaColorInputType} color - The hex value of the color.
* @param {string} name - The name of the color
*
* @throws Will throw an error if init has not been run before creating an instance.
*/
constructor(color: MoebiusChromaColorInputType, name: string);
/**
* Converts the color to an object in the specified color space.
* @param {string} type - The color space type (e.g., 'rgb' or 'hsl').
* @returns {MoebiusRGBObjectType | MoebiusHSLObjectType} The color object in the specified color space.
*/
toObject(type?: string): MoebiusRGBObjectType | MoebiusHSLObjectType;
/**
* Converts the color to a floating-point representation in the specified color space.
* @param {string} type - The color space type (e.g., 'rgb' or 'hsl').
* @returns {MoebiusRGBObjectType | MoebiusHSLObjectType} The floating-point representation of the color in the specified color space.
*/
toFloat(type?: string): MoebiusRGBObjectType | MoebiusHSLObjectType;
}
/**
* MoebiusPalettes class representing a set of color palettes and their variations.
*
*/
declare class MoebiusPalettes implements MoebiusPaletteInterface {
baseColor: MoebiusColorInterface;
secondaryColor: MoebiusColorInterface;
colors: Record<string, unknown> | MoebiusPaletteColorsInterface;
themes: Record<string, unknown> | MoebiusThemeColorsInterface;
defaultOptions: MoebiusPaletteDefaultOptionsType;
options: MoebiusPaletteOptionsType;
all: MoebiusColorValueHexType[];
accents: MoebiusPaletteAccentColorsInterface;
/**
* Creates an instance of MoebiusPalettes.
* @param {MoebiusPaletteOptionsType} options - Options for configuring the palettes.
*/
constructor(options: MoebiusPaletteOptionsType);
/**
* Generate a complement color palette based on the input color.
*
* @param {MoebiusChromaColorInputType} color - The base color for generating the complement palette.
* @param {MoebiusPaletteOptionsType} [options={}] - Options for generating the palette.<
* @param {number} [options.numberOfColors=8] - The number of colors in the complement palette.
* @param {string} [options.colorScaleMode] - The color scale mode for chroma-js.
* @param {boolean} [options.correctLightness=true] - Whether to correct lightness in the generated palette.
* @returns {MoebiusColorValueHexType[]} - Array of hex color values representing the complement palette.
*
* @example
* ```ts
* const baseColor = '#3498db';
* const complementPalette = complement(baseColor, { numberOfColors: 5 });
* console.log(complementPalette); // ['#3498db', '#db3434', '#75db34', '#dbd134', '#db7434']
* ```
*/
complement(color: MoebiusColorValueHexType, options?: Record<string, unknown> | MoebiusPaletteOptionsType): MoebiusColorValueHexType[];
/**
* Generates a dark mode color palette based on the provided base and secondary colors.
* @param {MoebiusChromaColorInputType} baseColor - The base color for the palette.
* @param {MoebiusChromaColorInputType} secondaryColor - The secondary color for the palette.
* @param {Record<string, unknown> | MoebiusPaletteOptionsType} [options={}] - Palette options.
* @param {boolean} [options.bezier=false] - Whether to use bezier interpolation for color scales.
* @param {string} [options.colorScaleMode] - The color scale mode for chroma.mix.
* @param {boolean} [options.noDuplicates=true] - Whether to remove duplicate colors from the palette.
* @returns {Record<string, MoebiusColorValueHexType[]>} - The generated dark mode color palette.
* @example
* ```ts
* const baseColor = '#3498db';
* const secondaryColor = '#2ecc71';
* const options = { bezier: true, colorScaleMode: 'lch' };
* const palette = darkMode(baseColor, secondaryColor, options);
* console.log(palette);
* ```
*/
darkMode(baseColor: MoebiusChromaColorInputType, secondaryColor: MoebiusChromaColorInputType, options?: Record<string, unknown> | MoebiusPaletteOptionsType): Record<string, MoebiusColorValueHexType[]>;
/**
* Generate a split color palette based on the input color.
*
* @param {MoebiusChromaColorInputType} color - The base color for generating the split palette.
* @param {MoebiusPaletteOptionsType} [options={}] - Options for generating the palette.
* @param {number} [options.numberOfColors=8] - The number of colors in the split palette.
* @param {string} [options.colorScaleMode] - The color scale mode for chroma-js.
* @param {boolean} [options.correctLightness=true] - Whether to correct lightness in the generated palette.
* @returns {MoebiusColorValueHexType[]} - Array of hex color values representing the split palette.
*
* @example
* ```ts
* const baseColor = '#3498db';
* const splitPalette = split(baseColor, { numberOfColors: 5 });
* console.log(splitPalette); // ['#3498db', '#99db34', '#dbd134', '#db3434', '#8f34db']
* ```
*/
split(color: MoebiusColorValueHexType, options?: Record<string, unknown> | MoebiusPaletteOptionsType): MoebiusColorValueHexType[];
/**
* Generates a triadic color palette based on the input color.
*
* @param {MoebiusChromaColorInputType} color - The input color in various formats (HEX, RGB, HSL, etc.).
* @param {Record<string, unknown> | MoebiusPaletteOptionsType} options - Additional options for palette generation.
* @param {number} [options.numberOfColors=8] - The number of colors in the generated palette.
* @param {string} [options.colorScaleMode] - The color scale mode for the generated palette.
* @param {boolean} [options.correctLightness=true] - Whether to correct lightness in the generated palette.
* @returns {MoebiusColorValueHexType[]} An array of HEX values representing the triadic color palette.
*
* @example
* ```ts
* const triadicPalette = triadic('#3498db', { numberOfColors: 5 });
* console.log(triadicPalette);
* // Output: ['#3498db', '#db344f', '#4fdb34', '#9834db', '#34db98']
* ```
*/
triadic(color: MoebiusColorValueHexType, options?: Record<string, unknown> | MoebiusPaletteOptionsType): MoebiusColorValueHexType[];
/**
* Generate a tetradic color palette based on the input color.
*
* @param {MoebiusChromaColorInputType} color - The base color for generating the tetradic palette.
* @param {MoebiusPaletteOptionsType} [options={}] - Options for generating the palette.
* @param {number} [options.numberOfColors=8] - The number of colors in the tetradic palette.
* @param {string} [options.colorScaleMode] - The color scale mode for chroma-js.
* @param {boolean} [options.correctLightness=true] - Whether to correct lightness in the generated palette.
* @returns {MoebiusColorValueHexType[]} - Array of hex color values representing the tetradic palette.
*
* @example
* ```ts
* const baseColor = '#3498db';
* const tetradicPalette = tetradic(baseColor, { numberOfColors: 5 });
* console.log(tetradicPalette); // ['#3498db', '#db3434', '#34db99', '#dbd134', '#8f34db']
* ```
*/
tetradic(color: MoebiusColorValueHexType, options?: Record<string, unknown> | MoebiusPaletteOptionsType): MoebiusColorValueHexType[];
/**
* Generate a pentadic color palette based on the input color.
*
* @param {MoebiusChromaColorInputType} color - The base color for generating the pentadic palette.
* @param {MoebiusPaletteOptionsType} [options={}] - Options for generating the palette.
* @param {number} [options.numberOfColors=8] - The number of colors in the pentadic palette.
* @param {string} [options.colorScaleMode] - The color scale mode for chroma-js.
* @param {boolean} [options.correctLightness=true] - Whether to correct lightness in the generated palette.
* @returns {MoebiusColorValueHexType[]} - Array of hex color values representing the pentadic palette.
*
* @example
* ```ts
* const baseColor = '#3498db';
* const pentadicPalette = pentadic(baseColor, { numberOfColors: 5 });
* console.log(pentadicPalette); // ['#3498db', '#dbd134', '#db3434', '#34db99', '#8f34db']
* ```
*/
pentadic(color: MoebiusColorValueHexType, options?: Record<string, unknown> | MoebiusPaletteOptionsType): MoebiusColorValueHexType[];
/**
* Generate a hexadic color palette based on the input color.
*
* @param {MoebiusChromaColorInputType} color - The base color for generating the hexadic palette.
* @param {MoebiusPaletteOptionsType} [options={}] - Options for generating the palette.
* @param {number} [options.numberOfColors=8] - The number of colors in the hexadic palette.
* @param {string} [options.colorScaleMode] - The color scale mode for chroma-js.
* @param {boolean} [options.correctLightness=true] - Whether to correct lightness in the generated palette.
* @returns {MoebiusColorValueHexType[]} - Array of hex color values representing the hexadic palette.
*
* @example
* ```ts
* const baseColor = '#3498db';
* const hexadicPalette = hexadic(baseColor, { numberOfColors: 5 });
* console.log(hexadicPalette); // ['#3498db', '#5d7f33', '#8473a9', '#ad7a95', '#db3434']
* ```
*/
hexadic(color: MoebiusColorValueHexType, options?: Record<string, unknown> | MoebiusPaletteOptionsType): MoebiusColorValueHexType[];
/**
* Generate an analogous color palette based on the input color.
*
* @param {MoebiusChromaColorInputType} color - The base color for generating the analogous palette.
* @param {MoebiusPaletteOptionsType} [options={}] - Options for generating the palette.
* @param {number} [options.numberOfColors=8] - The number of colors in the analogous palette.
* @param {string} [options.colorScaleMode] - The color scale mode for chroma-js.
* @param {boolean} [options.correctLightness=true] - Whether to correct lightness in the generated palette.
* @returns {MoebiusColorValueHexType[]} - Array of hex color values representing the analogous palette.
*
* @example
* ```ts
* const baseColor = '#3498db';
* const analogousPalette = analogous(baseColor, { numberOfColors: 5 });
* console.log(analogousPalette); // ['#3498db', '#75db34', '#dbd134', '#db7434', '#db3474']
* ```
*/
analogous(color: MoebiusColorValueHexType, options?: Record<string, unknown> | MoebiusPaletteOptionsType): MoebiusColorValueHexType[];
/**
* Interpolate between two colors and generate a color palette.
*
* @param {MoebiusChromaColorInputType} primaryColor - The starting color for interpolation.
* @param {MoebiusChromaColorInputType} secondaryColor - The ending color for interpolation.
* @param {MoebiusPaletteOptionsType} [options={}] - Options for generating the palette.
* @param {number} [options.numberOfColors=8] - The number of colors in the interpolated palette.
* @param {string} [options.colorScaleMode] - The color scale mode for chroma-js.
* @param {boolean} [options.bezier=false] - Whether to use bezier interpolation.
* @param {boolean} [options.correctLightness=true] - Whether to correct lightness in the generated palette.
* @returns {MoebiusColorValueHexType[]} - Array of hex color values representing the interpolated palette.
*
* @example
* ```ts
* const startColor = '#3498db';
* const endColor = '#db3434';
* const interpolatedPalette = interpolate(startColor, endColor, { numberOfColors: 5 });
* console.log(interpolatedPalette); // ['#3498db', '#5d6d7e', '#8473a9', '#ad7a95', '#db3434']
* ```
*/
interpolate(primaryColor: MoebiusColorValueHexType, secondaryColor: MoebiusColorValueHexType, options?: Record<string, unknown> | MoebiusPaletteOptionsType): MoebiusColorValueHexType[];
/**
* Generate a luminance shift palette based on an array of colors, with optional diverging colors.
*
* @param {MoebiusChromaColorInputType[]} colors - Array of base colors for generating the luminance shift palette.
* @param {MoebiusChromaColorInputType[]} [divergingColors=[]] - Array of diverging colors.
* @param {MoebiusPaletteOptionsType} [options={}] - Options for generating the palette.
* @param {number} [options.numberOfColors=8] - The total number of colors in the luminance shift palette.
* @param {boolean} [options.diverging=false] - Whether to generate a diverging palette.
* @param {string} [options.colorScaleMode] - The color scale mode for chroma-js.
* @param {boolean} [options.bezier=false] - Whether to use bezier interpolation.
* @param {string} [options.divergentColor='#f5f5f5'] - The divergent color for a diverging palette.
* @param {boolean} [options.correctLightness=true] - Whether to correct lightness in the generated palette.
* @returns {MoebiusColorValueHexType[]} - Array of hex color values representing the luminance shift palette.
*
* @example
* ```ts
* const baseColors = ['#3498db', '#99db34'];
* const divergingColors = ['#db3434'];
* const luminanceShiftPalette = luminanceShift(baseColors, divergingColors, { numberOfColors: 5 });
* console.log(luminanceShiftPalette); // ['#3498db', '#99db34', '#dbd134', '#db3434', '#8f34db']
* ```
*/
luminanceShift(colors: MoebiusColorValueHexType[], divergingColors?: MoebiusColorValueHexType[], options?: Record<string, unknown> | MoebiusPaletteOptionsType): MoebiusColorValueHexType[];
/**
* Generates a monochromatic color palette based on the given color.
* @param {MoebiusChromaColorInputType} color - The base color for the palette.
* @param {MoebiusPaletteOptionsType} options - Options for generating the palette.
* @returns {MoebiusColorValueHexType[]} - An array of hex color values in the palette.
* @example
* ```typescript
* const baseColor = '#003f5c';
* const options = { numberOfColors: 5, bezier: true, randomOffset: false };
* const monochromaticPalette = monochromatic(baseColor, options);
* console.log(monochromaticPalette);
* [
* '#003f5c', // maniacMansion,
* '#014268', // darkImperialBlue,
* '#024575', // macraggeBlue,
* '#044784', // bridgeport,
* '#064898', // frightNight,
* '#0745b6', // absoluteZero,
* '#002df5', // blueBouquet
* ];
* ```
*/
monochromatic(color: MoebiusColorValueHexType, options?: Record<string, unknown> | MoebiusPaletteOptionsType): MoebiusColorValueHexType[];
/**
* Generate a harmonized color palette based on the input color.
*
* @param {MoebiusChromaColorInputType} color - The base color for generating the harmonized palette.
* @param {number} start - The starting angle for generating harmonized colors (degrees).
* @param {number} end - The ending angle for generating harmonized colors (degrees).
* @param {number} interval - The interval between harmonized colors (degrees).
* @param {MoebiusPaletteOptionsType} [options={}] - Options for generating the palette.
* @param {boolean} [options.noDuplicates=true] - Whether to remove duplicate colors in the palette.
* @returns {MoebiusColorValueHexType[]} - Array of hex color values representing the harmonized palette.
*
* @example
* ```ts
* const baseColor = '#3498db';
* const harmonizedPalette = harmonize(baseColor, 30, 210, 30, { noDuplicates: true });
* console.log(harmonizedPalette); // ['#3498db', '#75db34', '#dbd134', '#db7434', '#3498db']
* ```
*/
harmonize(color: MoebiusColorValueHexType, start: number, end: number, interval: number, options?: Record<string, unknown> | MoebiusPaletteOptionsType): MoebiusColorValueHexType[];
}
/**
* Helper class for generating SVG paths for colored pie slices.
*/
declare class MoebiusSVGHelper {
xlmns: string;
/**
* Gets SVG paths for coloured pie slices based on the provided colors.
* @param {MoebiusColorValueHexType[][]} colors - Array of color groups.
* @param {number} [size=256] - Size of the SVG.
* @returns {DocumentFragment} - Document fragment containing the SVG paths.
* @example
* ```ts
* const svgHelper = new MoebiusSVGHelper();
* const colors = [['#ff0000', '#00ff00'], ['#0000ff']];
* const svgFragment = svgHelper.getColorPiePaths(colors, 256);
* document.body.appendChild(svgFragment);
* ```
*/
getColorPiePaths(colors: MoebiusColorValueHexType[][], size?: number): DocumentFragment;
}
/**
* Represents a color object with various color representations.
*/
interface MoebiusColorInterface {
color: MoebiusChromaColorInputType;
name: string;
hex: MoebiusColorValueHexType;
rgb: MoebiusColorValueRgbType;
hsl: MoebiusHSLObjectType;
hslFloat: MoebiusHSLObjectType;
rgbFloat: MoebiusRGBObjectType;
hwb: MoebiusHWBObjectType;
hsv: MoebiusHSVObjectType;
lab: MoebiusLABObjectType;
xyz: MoebiusXYZObjectType;
lch: MoebiusLCHObjectType;
oklch: MoebiusLCHObjectType;
hsi: MoebiusHSIObjectType;
oklab: MoebiusLABObjectType;
cmyk: MoebiusCMYKObjectType;
}
/**
* Describes a color with multiple representations and metadata.
*/
type MoebiusReturnType = Promise<{
MoebiusColor: typeof MoebiusColor;
MoebiusPalettes: typeof MoebiusPalettes;
MoebiusSVGHelper: typeof MoebiusSVGHelper;
}>;
/**
* Represents a full palette generated from a base/secondary color combination.
*/
interface MoebiusPaletteInterface {
baseColor: MoebiusColorInterface;
secondaryColor: MoebiusColorInterface;
colors: Record<string, unknown> | MoebiusPaletteColorsInterface;
themes: Record<string, unknown> | MoebiusThemeColorsInterface;
defaultOptions: MoebiusPaletteDefaultOptionsType;
options: MoebiusPaletteOptionsType;
all: MoebiusColorValueHexType[];
accents: MoebiusPaletteAccentColorsInterface;
}
/**
* Defines generated palette schemes (e.g., split, triadic).
*/
interface MoebiusPaletteColorsInterface {
interpolate: MoebiusColorValueHexType[];
luminanceShift: MoebiusColorValueHexType[];
monochromatic: MoebiusColorValueHexType[];
complement: MoebiusColorValueHexType[];
split: MoebiusColorValueHexType[];
triadic: MoebiusColorValueHexType[];
tetradic: MoebiusColorValueHexType[];
pentadic: MoebiusColorValueHexType[];
hexadic: MoebiusColorValueHexType[];
analogous: MoebiusColorValueHexType[];
}
/**
* Represents a palette of colors with different themes.
*/
interface MoebiusThemeColorsInterface {
darkMode: Record<string, MoebiusColorValueHexType[]>;
}
/**
* Represents a palette of accent colors with different schemes.
*/
interface MoebiusPaletteAccentColorsInterface {
interpolate: MoebiusColorValueHexType[][];
luminanceShift: MoebiusColorValueHexType[][];
monochromatic: MoebiusColorValueHexType[][];
complement: MoebiusColorValueHexType[][];
split: MoebiusColorValueHexType[][];
triadic: MoebiusColorValueHexType[][];
tetradic: MoebiusColorValueHexType[][];
pentadic: MoebiusColorValueHexType[][];
hexadic: MoebiusColorValueHexType[][];
analogous: MoebiusColorValueHexType[][];
}
/**
* Represents options for generating a color palette.
*/
type MoebiusPaletteOptionsType = {
baseColor: MoebiusColorInterface;
secondaryColor: MoebiusColorInterface;
divergentColor?: MoebiusColorValueHexType;
diverging?: boolean;
bezier?: boolean;
randomOffset?: boolean;
correctLightness?: boolean;
noDuplicates?: boolean;
colorScaleMode?: string;
divergingColor?: string;
reverseDirection?: boolean;
numberOfColors?: number;
};
/**
* Represents default options for generating a color palette.
*/
type MoebiusPaletteDefaultOptionsType = {
divergentColor?: MoebiusColorValueHexType;
diverging: boolean;
bezier: boolean;
randomOffset: boolean;
correctLightness: boolean;
noDuplicates: boolean;
colorScaleMode: string;
reverseDirection: boolean;
numberOfColors?: number;
};
/**
* A hex-based color string, e.g., '#ffcc00'.
*/
type MoebiusColorValueHexType = `#${string}`;
/**
* HSL color value string, e.g., 'hsl(240, 100%, 50%)'.
*/
type MoebiusColorValueHslType = `hsl(${number}, ${string}, ${string})`;
/**
* HSLA color value string, e.g., 'hsl(240, 100%, 50%, 0.5)'.
*/
type MoebiusColorValueHslaType = `hsl(${number}, ${string}, ${string}, ${number})`;
/**
* RGB color value string, e.g., 'rgb(255, 0, 0)'.
*/
type MoebiusColorValueRgbType = `rgb(${number}, ${number}, ${number})`;
/**
* RGBA color value string, e.g., 'rgb(255, 0, 0, 0.75)'.
*/
type MoebiusColorValueRgbaType = `rgb(${number}, ${number}, ${number}, ${number})`;
/**
* RGB color object.
*/
type MoebiusRGBObjectType = {
r: number;
g: number;
b: number;
};
/**
* HSL color object.
*/
type MoebiusHSLObjectType = {
h: number;
s: number;
l: number;
};
/**
* HSV color object.
*/
type MoebiusHSVObjectType = {
h: number;
s: number;
v: number;
};
/**
* HSI color object.
*/
type MoebiusHSIObjectType = {
h: number;
s: number;
i: number;
};
/**
* HWB color object.
*/
type MoebiusHWBObjectType = {
h: number;
w: number;
b: number;
};
/**
* LAB color object.
*/
type MoebiusLABObjectType = {
l: number;
a: number;
b: number;
};
/**
* LCH color object.
*/
type MoebiusLCHObjectType = {
l: number;
c: number;
h: number;
};
/**
* XYZ color object.
*/
type MoebiusXYZObjectType = {
x: number;
y: number;
z: number;
};
/**
* CMYK color object.
*/
type MoebiusCMYKObjectType = {
c: number;
m: number;
y: number;
k: number;
};
/**
* A named color + metadata for nearest-color matching source.
*/
interface NearestColorColorSpecInterface {
name: string;
source: string;
rgb: MoebiusRGBObjectType;
}
/**
* A matched color name and its RGB/hex representation.
*/
interface NearestColorColorMatchInterface {
name: string;
value: string;
rgb: MoebiusRGBObjectType;
}
/**
* Input types accepted by Chroma or Moebius logic.
*/
type MoebiusChromaColorInputType = MoebiusCMYKObjectType | MoebiusLCHObjectType | MoebiusHSLObjectType | MoebiusColorValueHexType | string;
/**
* Initializes and returns Moebius utilities with dynamic color naming support.
*
* This includes:
* - A subclass of `MoebiusColor` with nearest color name mapping
* - `MoebiusPalettes` for generating color palettes
* - `MoebiusSVGHelper` for generating SVG paths for colored pie slices.
*
* @function
* @async
* @returns {Promise<MoebiusReturnType>} An object containing Moebius utility classes
*
* @example
* ```ts
* const moebius = await Moebius();
* const color = new moebius.MoebiusColor('#abc123');
* console.log(color.name); // Closest color name, e.g., 'Avocado'
* ```
*/
declare function Moebius(): MoebiusReturnType;
//# sourceMappingURL=main.d.ts.map
export { Moebius as default };
export type { MoebiusCMYKObjectType, MoebiusChromaColorInputType, MoebiusColorInterface, MoebiusColorValueHexType, MoebiusColorValueHslType, MoebiusColorValueHslaType, MoebiusColorValueRgbType, MoebiusColorValueRgbaType, MoebiusHSIObjectType, MoebiusHSLObjectType, MoebiusHSVObjectType, MoebiusHWBObjectType, MoebiusLABObjectType, MoebiusLCHObjectType, MoebiusPaletteAccentColorsInterface, MoebiusPaletteColorsInterface, MoebiusPaletteDefaultOptionsType, MoebiusPaletteInterface, MoebiusPaletteOptionsType, MoebiusRGBObjectType, MoebiusReturnType, MoebiusThemeColorsInterface, MoebiusXYZObjectType, NearestColorColorMatchInterface, NearestColorColorSpecInterface };