@planet-matrix/mobius-model 0.4.0 → 0.6.0

package/src/color/rgb/internal.ts

@@ -0,0 +1,208 @@
+import {
+  internalAssertAlpha,
+  internalAssertColorUnit,
+  internalAssertFinite,
+  internalRoundColorFloat,
+} from "../internal.ts"
+
+import type {
+  HslColorValue,
+  HsvColorValue,
+  LinearRgbColorValue,
+  SrgbColorValue,
+} from "../types.ts"
+
+/**
+ * 匹配模块支持的十六进制颜色字符串格式。
+ */
+export const internalHexPattern: RegExp = /^#?(?:[\da-fA-F]{3}|[\da-fA-F]{4}|[\da-fA-F]{6}|[\da-fA-F]{8})$/
+
+/**
+ * 断言一个 sRGB 通道值是合法的 8 位整数。
+ */
+export const internalAssertByte = (value: number, channelName: string): void => {
+  if (Number.isInteger(value) === false || value < 0 || value > 255) {
+    throw new RangeError(`Color channel ${channelName} must be an integer between 0 and 255`)
+  }
+}
+
+/**
+ * 将色相角度规范化到 `0` 到 `360` 之间，`360` 会被折叠为 `0`。
+ */
+export const internalNormalizeHue = (value: number): number => {
+  internalAssertFinite(value, "Color hue")
+
+  const normalizedValue = value % 360
+  if (normalizedValue < 0) {
+    return normalizedValue + 360
+  }
+
+  return normalizedValue
+}
+
+/**
+ * 规范化 Linear RGB 颜色值结构。
+ */
+export const internalNormalizeLinearRgbColorValue = (color: LinearRgbColorValue): LinearRgbColorValue => {
+  internalAssertFinite(color.red, "Color channel red")
+  internalAssertFinite(color.green, "Color channel green")
+  internalAssertFinite(color.blue, "Color channel blue")
+  internalAssertAlpha(color.alpha)
+
+  return {
+    red: color.red,
+    green: color.green,
+    blue: color.blue,
+    alpha: color.alpha,
+  }
+}
+
+/**
+ * 规范化 sRGB 颜色值结构。
+ */
+export const internalNormalizeSrgbColorValue = (color: SrgbColorValue): SrgbColorValue => {
+  internalAssertByte(color.red, "red")
+  internalAssertByte(color.green, "green")
+  internalAssertByte(color.blue, "blue")
+  internalAssertAlpha(color.alpha)
+
+  return {
+    red: color.red,
+    green: color.green,
+    blue: color.blue,
+    alpha: color.alpha,
+  }
+}
+
+/**
+ * 规范化 HSL 颜色值结构。
+ */
+export const internalNormalizeHslColorValue = (color: HslColorValue): HslColorValue => {
+  internalAssertColorUnit(color.saturation, "saturation")
+  internalAssertColorUnit(color.lightness, "lightness")
+  internalAssertAlpha(color.alpha)
+
+  return {
+    hue: internalNormalizeHue(color.hue),
+    saturation: internalRoundColorFloat(color.saturation),
+    lightness: internalRoundColorFloat(color.lightness),
+    alpha: color.alpha,
+  }
+}
+
+/**
+ * 规范化 HSV 颜色值结构。
+ */
+export const internalNormalizeHsvColorValue = (color: HsvColorValue): HsvColorValue => {
+  internalAssertColorUnit(color.saturation, "saturation")
+  internalAssertColorUnit(color.value, "value")
+  internalAssertAlpha(color.alpha)
+
+  return {
+    hue: internalNormalizeHue(color.hue),
+    saturation: internalRoundColorFloat(color.saturation),
+    value: internalRoundColorFloat(color.value),
+    alpha: color.alpha,
+  }
+}
+
+/**
+ * 将短格式十六进制颜色扩展为长格式。
+ */
+export const internalExpandShortHex = (input: string): string => {
+  return input.split("").map(char => `${char}${char}`).join("")
+}
+
+/**
+ * 将 8 位通道值格式化为两位十六进制字符串。
+ */
+export const internalFormatHexByte = (value: number): string => {
+  return value.toString(16).padStart(2, "0").toUpperCase()
+}
+
+/**
+ * 将浮点数格式化为适合颜色字符串的紧凑小数字符串。
+ */
+export const internalFormatAlpha = (value: number): string => {
+  return Number(value.toFixed(4)).toString()
+}
+
+/**
+ * 将 `0` 到 `1` 的单位值格式化为百分比数值字符串，不附带 `%` 符号。
+ */
+export const internalFormatPercentUnit = (value: number): string => {
+  internalAssertColorUnit(value, "unit")
+  return Number((value * 100).toFixed(2)).toString()
+}
+
+/**
+ * 将 RGB 字符串通道解析为合法的 8 位通道值。
+ */
+export const internalParseRgbChannel = (input: string, channelName: string): number => {
+  const value = Number(input)
+  internalAssertByte(value, channelName)
+  return value
+}
+
+/**
+ * 将百分比字符串解析为 `0` 到 `1` 之间的单位值。
+ */
+export const internalParsePercentUnit = (input: string, channelName: string): number => {
+  if (input.endsWith("%") === false) {
+    throw new TypeError(`Invalid ${channelName} percentage input`)
+  }
+
+  return internalRoundColorFloat(Number(input.slice(0, -1)) / 100)
+}
+
+/**
+ * 将 8 位 sRGB 通道值转换为线性光通道值。
+ */
+export const internalGetLinearRgbChannelBySrgbChannel = (value: number): number => {
+  internalAssertByte(value, "sRGB")
+  const normalizedValue = value / 255
+
+  if (normalizedValue <= 0.040_45) {
+    return internalRoundColorFloat(normalizedValue / 12.92)
+  }
+
+  return internalRoundColorFloat(((normalizedValue + 0.055) / 1.055) ** 2.4)
+}
+
+/**
+ * 将线性光通道值转换为 8 位 sRGB 通道值。
+ */
+export const internalGetSrgbChannelByLinearRgbChannel = (value: number, channelName: string): number => {
+  internalAssertFinite(value, `Linear RGB channel ${channelName}`)
+
+  if (value < 0 || value > 1) {
+    throw new RangeError(`Linear RGB channel ${channelName} must be between 0 and 1 to convert to sRGB`)
+  }
+
+  if (value <= 0.003_130_8) {
+    return Math.round(value * 12.92 * 255)
+  }
+
+  return Math.round(((1.055 * (value ** (1 / 2.4))) - 0.055) * 255)
+}
+
+/**
+ * 根据输入字符串稳定生成一个 sRGB 颜色值。
+ */
+export const internalGetStableSrgbColorValueByString = (input: string): SrgbColorValue => {
+  let codePointSum = 0
+
+  for (const char of input) {
+    const codePoint = char.codePointAt(0)
+    if (codePoint !== undefined) {
+      codePointSum = codePointSum + codePoint
+    }
+  }
+
+  return {
+    red: Math.round(Math.abs(Math.sin(codePointSum) * 255)),
+    green: Math.round(Math.abs(Math.sin(codePointSum + 1) * 255)),
+    blue: Math.round(Math.abs(Math.sin(codePointSum + 2) * 255)),
+    alpha: 1,
+  }
+}

package/src/color/rgb/parse.ts

@@ -0,0 +1,302 @@
+import { internalAssertAlpha } from "../internal.ts"
+import {
+  createHslColorValue,
+  createHsvColorValue,
+  createSrgbColorValue,
+} from "./construct.ts"
+import {
+  hslColorValueToSrgbColorValue,
+  hsvColorValueToSrgbColorValue,
+} from "./convert.ts"
+import {
+  internalExpandShortHex,
+  internalHexPattern,
+  internalParsePercentUnit,
+  internalParseRgbChannel,
+} from "./internal.ts"
+
+import type {
+  HslColorValue,
+  HsvColorValue,
+  SrgbColorValue,
+} from "../types.ts"
+
+/**
+ * 判断输入是否为合法的十六进制颜色字符串。
+ *
+ * @example
+ * ```
+ * // Expect: true
+ * const example1 = isHexColorString("#F0A")
+ *
+ * // Expect: false
+ * const example2 = isHexColorString("#12")
+ * ```
+ */
+export const isHexColorString = (input: string): boolean => {
+  return internalHexPattern.test(input.trim())
+}
+
+/**
+ * 将十六进制颜色字符串解析为 sRGB 颜色值对象。
+ *
+ * @example
+ * ```
+ * // Expect: { red: 255, green: 0, blue: 170, alpha: 1 }
+ * const example1 = hexColorStringToSrgbColorValue("#F0A")
+ *
+ * // Expect: { red: 17, green: 34, blue: 51, alpha: 0.2667 }
+ * const example2 = hexColorStringToSrgbColorValue("#11223344")
+ * ```
+ */
+export const hexColorStringToSrgbColorValue = (input: string): SrgbColorValue => {
+  const normalizedInput = input.trim()
+  if (isHexColorString(normalizedInput) === false) {
+    throw new TypeError("Invalid hex color input")
+  }
+
+  const hex = normalizedInput.startsWith("#") ? normalizedInput.slice(1) : normalizedInput
+  const expandedHex = hex.length === 3 || hex.length === 4 ? internalExpandShortHex(hex) : hex
+  const red = Number.parseInt(expandedHex.slice(0, 2), 16)
+  const green = Number.parseInt(expandedHex.slice(2, 4), 16)
+  const blue = Number.parseInt(expandedHex.slice(4, 6), 16)
+  const alpha = expandedHex.length === 8
+    ? Number((Number.parseInt(expandedHex.slice(6, 8), 16) / 255).toFixed(4))
+    : 1
+
+  return createSrgbColorValue({ red, green, blue, alpha })
+}
+
+const internalParseRgbParts = (input: string, allowAlpha: boolean): SrgbColorValue => {
+  const rgbMatch = /^rgba?\((.*)\)$/i.exec(input)
+  if (rgbMatch === null) {
+    throw new TypeError("Invalid color string input")
+  }
+
+  const partsSource = rgbMatch[1]
+  if (partsSource === undefined) {
+    throw new TypeError("Invalid color string input")
+  }
+
+  const parts = partsSource.split(",").map(part => part.trim())
+  if (allowAlpha === true && parts.length !== 4) {
+    throw new TypeError("Invalid RGBA color string input")
+  }
+
+  if (allowAlpha === false && parts.length !== 3) {
+    throw new TypeError("Invalid RGB color string input")
+  }
+
+  const [redPart = "", greenPart = "", bluePart = "", alphaPart] = parts
+  const red = internalParseRgbChannel(redPart, "red")
+  const green = internalParseRgbChannel(greenPart, "green")
+  const blue = internalParseRgbChannel(bluePart, "blue")
+  const alpha = allowAlpha === true ? Number(alphaPart) : 1
+
+  return createSrgbColorValue({ red, green, blue, alpha })
+}
+
+/**
+ * 将 `rgb(r, g, b)` 字符串解析为 sRGB 颜色值对象。
+ *
+ * @example
+ * ```
+ * // Expect: { red: 51, green: 102, blue: 153, alpha: 1 }
+ * const example1 = rgbColorStringToSrgbColorValue("rgb(51, 102, 153)")
+ *
+ * // Expect: { red: 0, green: 0, blue: 0, alpha: 1 }
+ * const example2 = rgbColorStringToSrgbColorValue("rgb(0, 0, 0)")
+ * ```
+ */
+export const rgbColorStringToSrgbColorValue = (input: string): SrgbColorValue => {
+  return internalParseRgbParts(input.trim(), false)
+}
+
+/**
+ * 将 `rgba(r, g, b, a)` 字符串解析为 sRGB 颜色值对象。
+ *
+ * @example
+ * ```
+ * // Expect: { red: 51, green: 102, blue: 153, alpha: 0.5 }
+ * const example1 = rgbaColorStringToSrgbColorValue("rgba(51, 102, 153, 0.5)")
+ *
+ * // Expect: { red: 255, green: 255, blue: 255, alpha: 1 }
+ * const example2 = rgbaColorStringToSrgbColorValue("rgba(255, 255, 255, 1)")
+ * ```
+ */
+export const rgbaColorStringToSrgbColorValue = (input: string): SrgbColorValue => {
+  return internalParseRgbParts(input.trim(), true)
+}
+
+const internalParseHslParts = (input: string, allowAlpha: boolean): HslColorValue => {
+  const hslMatch = /^hsla?\((.*)\)$/i.exec(input)
+  if (hslMatch === null) {
+    throw new TypeError("Invalid color string input")
+  }
+
+  const partsSource = hslMatch[1]
+  if (partsSource === undefined) {
+    throw new TypeError("Invalid color string input")
+  }
+
+  const parts = partsSource.split(",").map(part => part.trim())
+  if (allowAlpha === true && parts.length !== 4) {
+    throw new TypeError("Invalid HSLA color string input")
+  }
+
+  if (allowAlpha === false && parts.length !== 3) {
+    throw new TypeError("Invalid HSL color string input")
+  }
+
+  const [huePart = "", saturationPart = "", lightnessPart = "", alphaPart] = parts
+  const hue = Number(huePart)
+  const saturation = internalParsePercentUnit(saturationPart, "saturation")
+  const lightness = internalParsePercentUnit(lightnessPart, "lightness")
+  const alpha = allowAlpha === true ? Number(alphaPart) : 1
+  internalAssertAlpha(alpha)
+
+  return createHslColorValue({ hue, saturation, lightness, alpha })
+}
+
+/**
+ * 将 `hsl(h, s%, l%)` 字符串解析为 HSL 颜色值对象。
+ *
+ * @example
+ * ```
+ * // Expect: { hue: 210, saturation: 0.5, lightness: 0.4, alpha: 1 }
+ * const example1 = hslColorStringToHslColorValue("hsl(210, 50%, 40%)")
+ *
+ * // Expect: { hue: 330, saturation: 0.5, lightness: 0.4, alpha: 1 }
+ * const example2 = hslColorStringToHslColorValue("hsl(-30, 50%, 40%)")
+ * ```
+ */
+export const hslColorStringToHslColorValue = (input: string): HslColorValue => {
+  return internalParseHslParts(input.trim(), false)
+}
+
+/**
+ * 将 `hsla(h, s%, l%, a)` 字符串解析为 HSL 颜色值对象。
+ *
+ * @example
+ * ```
+ * // Expect: { hue: 210, saturation: 0.5, lightness: 0.4, alpha: 0.5 }
+ * const example1 = hslaColorStringToHslColorValue("hsla(210, 50%, 40%, 0.5)")
+ *
+ * // Expect: { hue: 0, saturation: 0, lightness: 1, alpha: 1 }
+ * const example2 = hslaColorStringToHslColorValue("hsla(0, 0%, 100%, 1)")
+ * ```
+ */
+export const hslaColorStringToHslColorValue = (input: string): HslColorValue => {
+  return internalParseHslParts(input.trim(), true)
+}
+
+const internalParseHsvParts = (input: string, allowAlpha: boolean): HsvColorValue => {
+  const hsvMatch = /^hsva?\((.*)\)$/i.exec(input)
+  if (hsvMatch === null) {
+    throw new TypeError("Invalid color string input")
+  }
+
+  const partsSource = hsvMatch[1]
+  if (partsSource === undefined) {
+    throw new TypeError("Invalid color string input")
+  }
+
+  const parts = partsSource.split(",").map(part => part.trim())
+  if (allowAlpha === true && parts.length !== 4) {
+    throw new TypeError("Invalid HSVA color string input")
+  }
+
+  if (allowAlpha === false && parts.length !== 3) {
+    throw new TypeError("Invalid HSV color string input")
+  }
+
+  const [huePart = "", saturationPart = "", valuePart = "", alphaPart] = parts
+  const hue = Number(huePart)
+  const saturation = internalParsePercentUnit(saturationPart, "saturation")
+  const value = internalParsePercentUnit(valuePart, "value")
+  const alpha = allowAlpha === true ? Number(alphaPart) : 1
+  internalAssertAlpha(alpha)
+
+  return createHsvColorValue({ hue, saturation, value, alpha })
+}
+
+/**
+ * 将 `hsv(h, s%, v%)` 字符串解析为 HSV 颜色值对象。
+ *
+ * @example
+ * ```
+ * // Expect: { hue: 210, saturation: 0.6667, value: 0.6, alpha: 1 }
+ * const example1 = hsvColorStringToHsvColorValue("hsv(210, 66.67%, 60%)")
+ *
+ * // Expect: { hue: 30, saturation: 0.5, value: 0.6, alpha: 1 }
+ * const example2 = hsvColorStringToHsvColorValue("hsv(390, 50%, 60%)")
+ * ```
+ */
+export const hsvColorStringToHsvColorValue = (input: string): HsvColorValue => {
+  return internalParseHsvParts(input.trim(), false)
+}
+
+/**
+ * 将 `hsva(h, s%, v%, a)` 字符串解析为 HSV 颜色值对象。
+ *
+ * @example
+ * ```
+ * // Expect: { hue: 210, saturation: 0.6667, value: 0.6, alpha: 0.5 }
+ * const example1 = hsvaColorStringToHsvColorValue("hsva(210, 66.67%, 60%, 0.5)")
+ *
+ * // Expect: { hue: 0, saturation: 0, value: 1, alpha: 1 }
+ * const example2 = hsvaColorStringToHsvColorValue("hsva(0, 0%, 100%, 1)")
+ * ```
+ */
+export const hsvaColorStringToHsvColorValue = (input: string): HsvColorValue => {
+  return internalParseHsvParts(input.trim(), true)
+}
+
+/**
+ * 将异构颜色字符串归一化为 sRGB 颜色值对象。
+ *
+ * 这是一个面向最终显示层的归一化入口。它会有意把十六进制、RGB、HSL 与 HSV
+ * 等不同语义层的字符串统一折叠为 sRGB；如果调用方需要保留输入本身的颜色语义，
+ * 应改用对应的专用解析函数。
+ *
+ * @example
+ * ```
+ * // Expect: { red: 51, green: 102, blue: 153, alpha: 1 }
+ * const example1 = colorStringToSrgbColorValue("#336699")
+ *
+ * // Expect: { red: 51, green: 102, blue: 153, alpha: 1 }
+ * const example2 = colorStringToSrgbColorValue("hsl(210, 50%, 40%)")
+ * ```
+ */
+export const colorStringToSrgbColorValue = (input: string): SrgbColorValue => {
+  const normalizedInput = input.trim()
+  if (normalizedInput.startsWith("#") || isHexColorString(normalizedInput) === true) {
+    return hexColorStringToSrgbColorValue(normalizedInput)
+  }
+
+  if (normalizedInput.toLowerCase().startsWith("rgba(")) {
+    return rgbaColorStringToSrgbColorValue(normalizedInput)
+  }
+
+  if (normalizedInput.toLowerCase().startsWith("rgb(")) {
+    return rgbColorStringToSrgbColorValue(normalizedInput)
+  }
+
+  if (normalizedInput.toLowerCase().startsWith("hsla(")) {
+    return hslColorValueToSrgbColorValue(hslaColorStringToHslColorValue(normalizedInput))
+  }
+
+  if (normalizedInput.toLowerCase().startsWith("hsl(")) {
+    return hslColorValueToSrgbColorValue(hslColorStringToHslColorValue(normalizedInput))
+  }
+
+  if (normalizedInput.toLowerCase().startsWith("hsva(")) {
+    return hsvColorValueToSrgbColorValue(hsvaColorStringToHsvColorValue(normalizedInput))
+  }
+
+  if (normalizedInput.toLowerCase().startsWith("hsv(")) {
+    return hsvColorValueToSrgbColorValue(hsvColorStringToHsvColorValue(normalizedInput))
+  }
+
+  throw new TypeError("Invalid color string input")
+}

package/src/color/rgb/serialize.ts

@@ -0,0 +1,144 @@
+import {
+  createHslColorValue,
+  createHsvColorValue,
+  createSrgbColorValue,
+} from "./construct.ts"
+import {
+  internalFormatAlpha,
+  internalFormatHexByte,
+  internalFormatPercentUnit,
+} from "./internal.ts"
+
+import type {
+  HslColorValue,
+  HsvColorValue,
+  SrgbColorValue,
+} from "../types.ts"
+
+/**
+ * 将 sRGB 颜色值序列化为十六进制颜色字符串。
+ *
+ * @example
+ * ```
+ * // Expect: #336699
+ * const example1 = srgbColorValueToHexColorString({ red: 51, green: 102, blue: 153, alpha: 0.5 })
+ *
+ * // Expect: #33669980
+ * const example2 = srgbColorValueToHexColorString({ red: 51, green: 102, blue: 153, alpha: 0.5 }, { includeAlpha: true })
+ * ```
+ */
+export const srgbColorValueToHexColorString = (color: SrgbColorValue, options: { includeAlpha?: boolean } = {}): string => {
+  const normalizedColor = createSrgbColorValue(color)
+  const hex = [normalizedColor.red, normalizedColor.green, normalizedColor.blue]
+    .map(value => internalFormatHexByte(value))
+    .join("")
+
+  if (options.includeAlpha === true) {
+    const alphaByte = Math.round(normalizedColor.alpha * 255)
+    return `#${hex}${internalFormatHexByte(alphaByte)}`
+  }
+
+  return `#${hex}`
+}
+
+/**
+ * 将 sRGB 颜色值序列化为 `rgb(...)` 字符串。
+ *
+ * @example
+ * ```
+ * // Expect: rgb(51, 102, 153)
+ * const example1 = srgbColorValueToRgbColorString({ red: 51, green: 102, blue: 153, alpha: 0.5 })
+ *
+ * // Expect: rgb(0, 0, 0)
+ * const example2 = srgbColorValueToRgbColorString({ red: 0, green: 0, blue: 0, alpha: 1 })
+ * ```
+ */
+export const srgbColorValueToRgbColorString = (color: SrgbColorValue): string => {
+  const normalizedColor = createSrgbColorValue(color)
+  return `rgb(${normalizedColor.red}, ${normalizedColor.green}, ${normalizedColor.blue})`
+}
+
+/**
+ * 将 sRGB 颜色值序列化为 `rgba(...)` 字符串。
+ *
+ * @example
+ * ```
+ * // Expect: rgba(51, 102, 153, 0.5)
+ * const example1 = srgbColorValueToRgbaColorString({ red: 51, green: 102, blue: 153, alpha: 0.5 })
+ *
+ * // Expect: rgba(255, 255, 255, 1)
+ * const example2 = srgbColorValueToRgbaColorString({ red: 255, green: 255, blue: 255, alpha: 1 })
+ * ```
+ */
+export const srgbColorValueToRgbaColorString = (color: SrgbColorValue): string => {
+  const normalizedColor = createSrgbColorValue(color)
+  return `rgba(${normalizedColor.red}, ${normalizedColor.green}, ${normalizedColor.blue}, ${internalFormatAlpha(normalizedColor.alpha)})`
+}
+
+/**
+ * 将 HSL 颜色值序列化为 `hsl(...)` 字符串。
+ *
+ * @example
+ * ```
+ * // Expect: hsl(210, 50%, 40%)
+ * const example1 = hslColorValueToHslColorString({ hue: 210, saturation: 0.5, lightness: 0.4, alpha: 0.5 })
+ *
+ * // Expect: hsl(0, 0%, 100%)
+ * const example2 = hslColorValueToHslColorString({ hue: 0, saturation: 0, lightness: 1, alpha: 1 })
+ * ```
+ */
+export const hslColorValueToHslColorString = (color: HslColorValue): string => {
+  const normalizedColor = createHslColorValue(color)
+  return `hsl(${normalizedColor.hue}, ${internalFormatPercentUnit(normalizedColor.saturation)}%, ${internalFormatPercentUnit(normalizedColor.lightness)}%)`
+}
+
+/**
+ * 将 HSL 颜色值序列化为 `hsla(...)` 字符串。
+ *
+ * @example
+ * ```
+ * // Expect: hsla(210, 50%, 40%, 0.5)
+ * const example1 = hslColorValueToHslaColorString({ hue: 210, saturation: 0.5, lightness: 0.4, alpha: 0.5 })
+ *
+ * // Expect: hsla(0, 0%, 100%, 1)
+ * const example2 = hslColorValueToHslaColorString({ hue: 0, saturation: 0, lightness: 1, alpha: 1 })
+ * ```
+ */
+export const hslColorValueToHslaColorString = (color: HslColorValue): string => {
+  const normalizedColor = createHslColorValue(color)
+  return `hsla(${normalizedColor.hue}, ${internalFormatPercentUnit(normalizedColor.saturation)}%, ${internalFormatPercentUnit(normalizedColor.lightness)}%, ${internalFormatAlpha(normalizedColor.alpha)})`
+}
+
+/**
+ * 将 HSV 颜色值序列化为 `hsv(...)` 字符串。
+ *
+ * @example
+ * ```
+ * // Expect: hsv(210, 66.67%, 60%)
+ * const example1 = hsvColorValueToHsvColorString({ hue: 210, saturation: 0.6667, value: 0.6, alpha: 0.5 })
+ *
+ * // Expect: hsv(0, 0%, 100%)
+ * const example2 = hsvColorValueToHsvColorString({ hue: 0, saturation: 0, value: 1, alpha: 1 })
+ * ```
+ */
+export const hsvColorValueToHsvColorString = (color: HsvColorValue): string => {
+  const normalizedColor = createHsvColorValue(color)
+  return `hsv(${normalizedColor.hue}, ${internalFormatPercentUnit(normalizedColor.saturation)}%, ${internalFormatPercentUnit(normalizedColor.value)}%)`
+}
+
+/**
+ * 将 HSV 颜色值序列化为 `hsva(...)` 字符串。
+ *
+ * @example
+ * ```
+ * // Expect: hsva(210, 66.67%, 60%, 0.5)
+ * const example1 = hsvColorValueToHsvaColorString({ hue: 210, saturation: 0.6667, value: 0.6, alpha: 0.5 })
+ *
+ * // Expect: hsva(0, 0%, 100%, 1)
+ * const example2 = hsvColorValueToHsvaColorString({ hue: 0, saturation: 0, value: 1, alpha: 1 })
+ * ```
+ */
+export const hsvColorValueToHsvaColorString = (color: HsvColorValue): string => {
+  const normalizedColor = createHsvColorValue(color)
+  return `hsva(${normalizedColor.hue}, ${internalFormatPercentUnit(normalizedColor.saturation)}%, ${internalFormatPercentUnit(normalizedColor.value)}%, ${internalFormatAlpha(normalizedColor.alpha)})`
+}

package/src/color/types.ts

@@ -0,0 +1,57 @@
+/**
+ * 表示 XYZ 颜色值结构，使用 `x`、`y`、`z` 三个通道和 `alpha` 透明度通道。
+ */
+export type XyzColorValue = Readonly<{
+  x: number
+  y: number
+  z: number
+  alpha: number
+}>
+
+/**
+ * 表示基于 XYZ 颜色值计算得到的 `xy` 色度坐标结构。
+ */
+export type XyChromaticityValue = Readonly<{
+  x: number
+  y: number
+}>
+
+/**
+ * 表示 Linear RGB 颜色值结构，使用线性 `red`、`green`、`blue` 三个通道和 `alpha` 透明度通道。
+ */
+export type LinearRgbColorValue = Readonly<{
+  red: number
+  green: number
+  blue: number
+  alpha: number
+}>
+
+/**
+ * 表示 sRGB 颜色值结构，使用 `red`、`green`、`blue` 三个 8 位通道和 `alpha` 透明度通道。
+ */
+export type SrgbColorValue = Readonly<{
+  red: number
+  green: number
+  blue: number
+  alpha: number
+}>
+
+/**
+ * 表示 HSL 颜色值结构，使用 `hue`、`saturation`、`lightness` 和 `alpha` 四个通道。
+ */
+export type HslColorValue = Readonly<{
+  hue: number
+  saturation: number
+  lightness: number
+  alpha: number
+}>
+
+/**
+ * 表示 HSV 颜色值结构，使用 `hue`、`saturation`、`value` 和 `alpha` 四个通道。
+ */
+export type HsvColorValue = Readonly<{
+  hue: number
+  saturation: number
+  value: number
+  alpha: number
+}>