From bfb52035963e442a6a4cd480032e3adb8fdbc444 Mon Sep 17 00:00:00 2001 From: Adam Thompson-Sharpe Date: Wed, 26 Jun 2024 13:05:57 -0400 Subject: [PATCH 1/2] [types] Re-export types for `index` and `index-fn` (#555) --- src/index-fn.js | 38 ++++++++++++++++++++++++++++++++++++++ src/index.d.ts | 37 +++++++++++++++++++++++++++++++++++++ 2 files changed, 75 insertions(+) diff --git a/src/index-fn.js b/src/index-fn.js index 00928460b..dc7d0df12 100644 --- a/src/index-fn.js +++ b/src/index-fn.js @@ -34,3 +34,41 @@ export {default as deltaEMethods} from "./deltaE/index.js"; export * from "./variations.js"; export { mix, steps, range, isRange } from "./interpolation.js"; export * from "./spaces/index-fn.js"; + +// Type re-exports +// Re-exported from src/color.d.ts +/** @typedef {import("./types.js").ColorConstructor} ColorConstructor */ +/** @typedef {import("./types.js").ColorObject} ColorObject */ +/** @typedef {import("./types.js").ColorTypes} ColorTypes */ +/** @typedef {import("./types.js").Coords} Coords */ +/** @typedef {import("./types.js").DefineFunctionCode} DefineFunctionCode */ +/** @typedef {import("./types.js").DefineFunctionOptions} DefineFunctionOptions */ +/** @typedef {import("./types.js").DefineFunctionHybrid} DefineFunctionHybrid */ +/** @typedef {import("./types.js").PlainColorObject} PlainColorObject */ +/** @typedef {import("./types.js").SpaceAccessor} SpaceAccessor */ +/** + * @typedef {import("./types.js").ToColorPrototype} ToColorPrototype + * @template {(...args: any[]) => any} T + */ +// Re-exported from src/adapt.d.ts +/** @typedef {import("./types.js").White} White */ +// Re-exported from src/CATs.d.ts +/** @typedef {import("./types.js").CAT} CAT */ +// Re-exported from src/display.d.ts +/** @typedef {import("./types.js").Display} Display */ +// Re-exported from src/interpolation.d.ts +/** @typedef {import("./types.js").Range} Range */ +/** @typedef {import("./types.js").RangeOptions} RangeOptions */ +/** @typedef {import("./types.js").MixOptions} MixOptions */ +/** @typedef {import("./types.js").StepsOptions} StepsOptions */ +// Re-exported from src/parse.d.ts +/** @typedef {import("./types.js").ParseOptions} ParseOptions */ +// Re-exported from src/rgbspace.d.ts +/** @typedef {import("./types.js").RGBOptions} RGBOptions */ +// Re-exported from src/serialize.d.ts +/** @typedef {import("./types.js").SerializeOptions} SerializeOptions */ +// Re-exported from src/space.d.ts +/** @typedef {import("./types.js").Format} SpaceFormat */ +/** @typedef {import("./types.js").CoordMeta} CoordMeta */ +/** @typedef {import("./types.js").Ref} Ref */ +/** @typedef {import("./types.js").SpaceOptions} SpaceOptions */ diff --git a/src/index.d.ts b/src/index.d.ts index 73bc03a39..565c8788b 100644 --- a/src/index.d.ts +++ b/src/index.d.ts @@ -22,6 +22,43 @@ import { range, Range, MixOptions, StepsOptions } from "./interpolation.js"; import { getLuminance } from "./luminance.js"; import { lighten, darken } from "./variations.js"; +// Type re-exports +export { + // Re-exported from src/color.d.ts + ColorConstructor, + ColorObject, + ColorTypes, + Coords, + DefineFunctionCode, + DefineFunctionOptions, + DefineFunctionHybrid, + PlainColorObject, + SpaceAccessor, + ToColorPrototype, + // Re-exported from src/adapt.d.ts + White, + // Re-exported from src/CATs.d.ts + CAT, + // Re-exported from src/display.d.ts + Display, + // Re-exported from src/interpolation.d.ts + Range, + RangeOptions, + MixOptions, + StepsOptions, + // Re-exported from src/parse.d.ts + ParseOptions, + // Re-exported from src/rgbspace.d.ts + RGBOptions, + // Re-exported from src/serialize.d.ts + SerializeOptions, + // Re-exported from src/space.d.ts + Format as SpaceFormat, + CoordMeta, + Ref, + SpaceOptions, +} from "./types.js"; + // Augment existing Color object declare module "./color" { export default class Color { From f7c2c35247737b88e05fa3c8e9acf2f8730cc20e Mon Sep 17 00:00:00 2001 From: Lloyd Kupchanko Date: Wed, 26 Jun 2024 14:57:20 -0600 Subject: [PATCH 2/2] Fix types and type tests (#565) --- src/color.d.ts | 7 +- src/deltaE.js | 2 +- src/deltas.js | 7 +- src/display.js | 1 + src/inGamut.js | 4 +- src/space.d.ts | 150 ------------------------ src/toGamut.js | 10 +- src/types.d.ts | 6 +- types/test/{spaces.ts => ColorSpace.ts} | 2 +- 9 files changed, 26 insertions(+), 163 deletions(-) delete mode 100644 src/space.d.ts rename types/test/{spaces.ts => ColorSpace.ts} (96%) diff --git a/src/color.d.ts b/src/color.d.ts index 563ec8783..5d04bc102 100644 --- a/src/color.d.ts +++ b/src/color.d.ts @@ -8,6 +8,7 @@ import hooks from "./hooks.js"; import * as util from "./util.js"; import ColorSpace, { Ref } from "./ColorSpace.js"; import SpaceAccessors from "./space-coord-accessors.js"; +import { ToGamutOptions } from "./types.js"; import { to as toFn, @@ -86,7 +87,6 @@ declare namespace Color { export const to: ToColorNamespace; export const equals: ToColorNamespace; export const inGamut: ToColorNamespace; - export const toGamut: ToColorNamespace; export const distance: ToColorNamespace; // `get` is defined below as a static method on the Class, // and `toString` is intentionally not overridden for the namespace @@ -100,6 +100,8 @@ declare namespace Color { export function set (color: ColorTypes, props: Record number)>): Color; export function setAll (color: ColorTypes, coords: Coords, alpha?: number): Color; export function setAll (color: ColorTypes, space: string | ColorSpace, coords: Coords, alpha?: number): Color; + export function toGamut (color: ColorTypes, options?: ToGamutOptions): Color; + export function toGamut (color: ColorTypes, space?: string): Color; } /** @@ -155,7 +157,6 @@ declare class Color extends SpaceAccessors implements PlainColorObject { to: ToColorPrototype; equals: ToColorPrototype; inGamut: ToColorPrototype; - toGamut: ToColorPrototype; distance: ToColorPrototype; toString: ToColorPrototype; @@ -165,6 +166,8 @@ declare class Color extends SpaceAccessors implements PlainColorObject { set (props: Record number)>): Color; setAll (coords: Coords, alpha?: number): Color; setAll (space: string | ColorSpace, coords: Coords, alpha?: number): Color; + toGamut (options?: ToGamutOptions): Color; + toGamut (space?: string): Color; } export default Color; diff --git a/src/deltaE.js b/src/deltaE.js index 733761be4..6e80ad93c 100644 --- a/src/deltaE.js +++ b/src/deltaE.js @@ -10,7 +10,7 @@ import deltaEMethods from "./deltaE/index.js"; * * @param {ColorTypes} c1 * @param {ColorTypes} c2 - * @param {Methods | ({ method: Methods } & Record} o + * @param {Methods | ({ method: Methods } & Record)} o * deltaE method to use as well as any other options to pass to the deltaE function * @returns {number} * @throws {TypeError} Unknown or unspecified method diff --git a/src/deltas.js b/src/deltas.js index 46d536761..1d0ebe658 100644 --- a/src/deltas.js +++ b/src/deltas.js @@ -4,10 +4,13 @@ import to from "./to.js"; import { adjust } from "./angles.js"; import { isNone } from "./util.js"; +// Type "imports" +/** @typedef {import("./types.js").ColorTypes} ColorTypes */ + /** * Get color differences per-component, on any color space - * @param {Color} c1 - * @param {Color} c2 + * @param {ColorTypes} c1 + * @param {ColorTypes} c2 * @param {object} options * @param {string | ColorSpace} [options.space=c1.space] - The color space to use for the delta calculation. Defaults to the color space of the first color. * @param {string} [options.hue="shorter"] - How to handle hue differences. Same as hue interpolation option. diff --git a/src/display.js b/src/display.js index 1e987283d..8b4219407 100644 --- a/src/display.js +++ b/src/display.js @@ -11,6 +11,7 @@ import sRGB from "./spaces/srgb.js"; // Type "imports" /** @typedef {import("./types.js").ColorTypes} ColorTypes */ /** @typedef {import("./types.js").Display} Display */ +/** @typedef {import("./ColorSpace.js").default} ColorSpace */ // Default space for CSS output. Code in Color.js makes this wider if there's a DOM available defaults.display_space = sRGB; diff --git a/src/inGamut.js b/src/inGamut.js index d0aaddac8..84f2434b9 100644 --- a/src/inGamut.js +++ b/src/inGamut.js @@ -9,8 +9,8 @@ const ε = .000075; /** * Check if a color is in gamut of either its own or another color space * @param {ColorTypes} color - * @param {string | ColorSpace} space - * @param {{ epsilon?: number | undefined }} param2 + * @param {string | ColorSpace} [space] + * @param {{ epsilon?: number | undefined }} [param2] * @returns {boolean} */ export default function inGamut (color, space, {epsilon = ε} = {}) { diff --git a/src/space.d.ts b/src/space.d.ts deleted file mode 100644 index f1658e183..000000000 --- a/src/space.d.ts +++ /dev/null @@ -1,150 +0,0 @@ -/** - * @packageDocumentation - * Defines the class and other types related to creating color spaces. - * For the builtin color spaces, see the `spaces` module. - */ -import { White } from "./adapt.js"; -import { ColorConstructor, Coords, ColorTypes } from "./color.js"; -import type FormatClass from "./Format.js"; -import type { instance } from "./Format.js"; - -export interface Format { - /** @default "function" */ - type?: string | undefined; - /** @default "color" */ - name?: string | undefined; - id?: string | undefined; - coords?: string[] | undefined; - coordGrammar?: (string & { range?: [number, number] })[] | undefined; - serializeCoords?: - | ((coords: Coords, precision: number) => [string, string, string]) - | undefined; - /** Whether to adjust the coordinates to fit in the gamut */ - toGamut?: boolean | undefined; - /** Whether commas should separate arguments for a format */ - commas?: boolean | undefined; - /** Whether to always have alpha at the end (true), never (false), or auto (undefined) */ - alpha?: boolean | undefined; - test?: ((str: string) => boolean) | undefined; - /** Function to parse a string into a color */ - parse?: ((str: string) => ColorConstructor) | undefined; - /** - * Serialize coordinates and an alpha channel into a string. - * Must be defined for a format to support serialization - */ - serialize?: ((coords: Coords, alpha: number, opts?: Record) => string) | undefined; - [instance]?: FormatClass | undefined; -} - -export interface CoordMeta { - name?: string | undefined; - type?: string | undefined; - range?: [number, number] | undefined; - refRange?: [number, number] | undefined; -} - -export interface SpaceOptions { - /** Id of this space, used in things such as conversions */ - id: string; - /** The readable name of the space, used in user-facing UI */ - name: string; - /** The base color space */ - base?: string | ColorSpace | null | undefined; - /** - * Function that converts coords in the base color space to coords in this color space. - * Must perform chromatic adaptation if needed - */ - fromBase?: ((coords: Coords) => number[]) | undefined; - /** - * Function that converts coords in this color space to coords in the base color space. - * Must perform chromatic adaptation if needed - */ - toBase?: ((coords: Coords) => number[]) | undefined; - /** - * Object mapping coord ids to coord metadata - * @see {@link CoordMeta} - */ - coords?: Record | undefined; - white?: string | White | undefined; - /** The ID used by CSS, such as `display-p3` or `--cam16-jmh` */ - cssId?: string | undefined; - referred?: string | undefined; - /** - * Details about string formats to parse from / serialize to - * @see {@link Format} - */ - formats?: Record | undefined; - gamutSpace?: "self" | string | ColorSpace | null | undefined; -} - -export type Ref = - | string - | [string | ColorSpace, string] - | { space: string | ColorSpace; coordId: string }; - -/** Class for color spaces. Each color space corresponds to a `ColorSpace` instance */ -export default class ColorSpace { - constructor (options: SpaceOptions); - - static DEFAULT_FORMAT: { type: "functions"; name: "color" }; - - /** - * @throws {TypeError} If no matching color space is found - */ - static get ( - space: ColorSpace | string, - ...alternatives: (ColorSpace | string)[] - ): ColorSpace; - - /** - * @throws {TypeError} If no space or an unknown space is provided - */ - static resolveCoord ( - ref: Ref, - workingSpace?: string | ColorSpace - ): CoordMeta & { - id: string; - index: string | number; - space: ColorSpace; - }; - - /** - * @throws {TypeError} If a space with the provided id already exists - */ - static register (space: ColorSpace): ColorSpace; - static register (id: string, space: ColorSpace): ColorSpace; - - static registry: Record; - - get all (): Set; - /** The ID used by CSS, such as `display-p3` or `--cam16-jmh` */ - get cssId (): string; - get isPolar (): boolean; - get isUnbounded (): boolean; - - name: string; - id: string; - aliases?: string[] | undefined; - base: ColorSpace | null; - coords: Record; - fromBase?: ((coords: Coords) => number[]) | undefined; - toBase?: ((coords: Coords) => number[]) | undefined; - formats: Record; - referred?: string | undefined; - white: White; - gamutSpace: ColorSpace; - - from (color: ColorTypes): Coords; - from (space: string | ColorSpace, coords: Coords): Coords; - - getFormat (format?: string | Format): Format | null; - - getMinCoords (): Coords; - - inGamut (coords: Coords, options?: { epsilon?: number }): boolean; - - to (color: ColorTypes): Coords; - to (space: string | ColorSpace, coords: Coords): Coords; - - toString (): string; -} diff --git a/src/toGamut.js b/src/toGamut.js index 238d1a548..f091292ff 100644 --- a/src/toGamut.js +++ b/src/toGamut.js @@ -49,11 +49,17 @@ const GMAPPRESET = { /** * Force coordinates to be in gamut of a certain color space. * Mutates the color it is passed. + * @overload * @param {ColorTypes} color - * @param {ToGamutOptions | string} param1 + * @param {ToGamutOptions} [options] + * @returns {PlainColorObject} + */ +/** + * @overload + * @param {ColorTypes} color + * @param {string} [space] * @returns {PlainColorObject} */ - export default function toGamut ( color, { diff --git a/src/types.d.ts b/src/types.d.ts index 799346b9e..90e3c15f1 100644 --- a/src/types.d.ts +++ b/src/types.d.ts @@ -135,10 +135,10 @@ export interface SerializeOptions { } // space.js -import type ColorSpace from "./space.js"; -import type { Format, Ref, SpaceOptions } from "./space.js"; +import type ColorSpace from "./ColorSpace.js"; +import type { Format, Ref, SpaceOptions } from "./ColorSpace.js"; export type { ColorSpace }; -export type * from "./space.js"; +export type * from "./ColorSpace.js"; // toGamut.js export interface ToGamutOptions { diff --git a/types/test/spaces.ts b/types/test/ColorSpace.ts similarity index 96% rename from types/test/spaces.ts rename to types/test/ColorSpace.ts index cbb233098..675bf1786 100644 --- a/types/test/spaces.ts +++ b/types/test/ColorSpace.ts @@ -1,5 +1,5 @@ import Color from "colorjs.io/src"; -import ColorSpace from "colorjs.io/src/space"; +import ColorSpace from "colorjs.io/src/ColorSpace"; // @ts-expect-error new ColorSpace();