Update Colors Config docs

packages/docs/locales/en.json

@@ -4293,7 +4293,7 @@
     },
     "reactivity": {
       "subtitle": "Reactivity",
-      "about": "Methods like `getColors` return a computed reactives that can also be accessed by variable `colors`. The advantage is allow to change properties, instead of rewriting whole colors variable. For example, you can change `primary` color by writing `colors.primary = '#ff0'`. Multiple properties changes are also supported, you can write `setColors({'{ primary: `#00f`, secondary: `#0ff` }'})`."
+      "about": "Methods like `getColors` return a computed reactives that can also be accessed by variable `colors`. The advantage is allow to change properties, instead of rewriting whole colors variable. For example, you can change `primary` color by writing `colors.primary = \"#ff0\"`. Multiple properties changes are also supported, you can write `setColors({'{ primary: \"#00f\", secondary: \"#0ff\" }'})`."
     },
     "otherServices": {
       "subtitle": "Colors config with other services",
@@ -4302,19 +4302,30 @@
       "css": "CSS-variables do also respect the color config and dynamically change their values!"
     },
     "api": {
-      "title": "Icon config service API",
+      "title": "Colors config service API",
       "types": "Types",
-      "ColorConfig": "An object where the keys are the color names and the values are valid CSS colors.",
-      "ColorInput": "A valid CSS color",
+      "colorConfig": "Configuration object where is defined color variables, threshold, presets and current preset name.",
+      "cssColor": "A valid CSS color.",
+      "essentialVariables": "An object where the keys are the color names and values are valid CSS colors.",
+      "colorVariables": "An object where the keys are the color names and values are valid CSS colors.",
       "methods": "Methods",
-      "useColors": "Return colors methods and variables",
+      "applyPreset": "Applies preset by its name to the colors config.",
+      "useColors": "Return colors methods and variables.",
       "setColors": "Used to merge new colors into config or update existing colors.",
-      "getColors": "Returns current color config",
-      "getColor": "Return color by name",
+      "getColors": "Returns current color config.",
+      "getColor": "Return color by name.",
+      "getComputedColor": "Returns compute color from colors variables.",
       "getBoxShadowColor": "Return a color that is appropriate to be used for the `box-shadow`.",
+      "getBoxShadowColorFromBg": "Return a color that is appropriate to be used for the `box-shadow`.",
       "getHoverColor": "Return a color that you can use as a `hover` color.",
       "getFocusColor": "Return a color that you can use as a `focus` color.",
       "getGradientBackground": "Return a gradient-color that you can use as a `background-image` CSS property's value.",
+      "getTextColor": "Returns a color depending on the background lightness.",
+      "shiftHSLAColor": "Returns shifted HSLA color.",
+      "setHSLAColor": "Sets HSLA color.",
+      "colorsToCSSVariable": "Converts object of colors to the object of named css variables.",
+      "colorToRgba": "Converts named color to the `rgba` string.",
+      "getStateMaskGradientBackground": "Returns a CSS linear-background value for the `background-image` property.",
       "hookMethods": "useColors hook methods.",
       "hookVariables": "useColors hook variables.",
       "colors": "A computed reactive where the keys are color names and values are valid CSS colors."

packages/docs/locales/ru.json

@@ -4195,23 +4195,33 @@
       "css": "Также переменные CSS имеют те же цветовые переменные, которые вы определяете в конфигурации цвета, которые динамически меняются вместе с конфигурацией цветов:"
     },
     "api": {
-      "title": "API конфигурации иконок",
+      "title": "API конфигурации цветов",
       "types": "Типы",
-      "ColorConfig": "Объект, где ключ - это имя цвета, а значение - валидный цвет CSS",
-      "ColorInput": " Валидный цвет CSS",
+      "colorConfig": "Объект конфигурации где указываются такие свойства как переменные цветов, пороговое значение для определения яркости цвета (threshold), пресеты и название текущего пресета.",
+      "cssColor": "Валидный CSS цвет.",
+      "essentialVariables": "Объект, где ключ - это название или имя цвета, а значение - валидный цвет CSS.",
+      "colorVariables": "Объект, где ключ - это название или имя цвета, а значение - валидный цвет CSS.",
       "methods": "Методы",
-      "useColor": "Возвращает методы для работы с цветом",
-      "setColors": "Используется для объединения новых цветов в конфигурацию или обновления существующих цветов",
-      "getColors": "Возвращает текущую конфигурацию цветов",
-      "getColor": "Возвращает цвет по имени",
-      "getBoxShadowColor": "Возвращает цвет, который вы можете использовать как цвет для `box-shadow`",
-      "getHoverColor": "Возвращает цвет, который вы можете использовать как цвет для `hover`",
-      "getFocusColor": "Возвращает цвет, который вы можете использовать как цвет для `focus`",
-      "getGradientBackground": "Возвращает цвет, который вы можете использовать как цвет для css атрибута `background`",
-      "hookMethods": "useColors хуки",
-      "useColors": "Return colors methods and variables",
-      "hookVariables": "useColors hook variables.",
-      "colors": "A computed reactive where the keys are color names and values are valid CSS colors."
+      "applyPreset": "Применяет именновый цветовой пресет к цветовой конфигурации.",
+      "useColor": "Возвращает методы для работы с цветом.",
+      "setColors": "Используется для объединения новых цветов в конфигурацию или обновления существующих цветов.",
+      "getColors": "Возвращает текущую конфигурацию цветов.",
+      "getColor": "Возвращает цвет по имени.",
+      "getBoxShadowColor": "Возвращает цвет, который вы можете использовать как цвет для `box-shadow`.",
+      "getBoxShadowColorFromBg": "Возвращает цвет, который вы можете использовать как цвет для `box-shadow`.",
+      "getHoverColor": "Возвращает цвет, который вы можете использовать как цвет для `hover`.",
+      "getFocusColor": "Возвращает цвет, который вы можете использовать как цвет для `focus`.",
+      "getGradientBackground": "Возвращает цвет, который вы можете использовать как цвет для css атрибута `background`.",
+      "getTextColor": "Возвращает цвет зависимый от яркости фонового цвета.",
+      "shiftHSLAColor": "Задает и возвращает смещение HSLA цвета.",
+      "setHSLAColor": "Задает HSLA цвет.",
+      "colorsToCSSVariable": "Конвертируерт объект с именноваными цветами в объект с CSS переменными.",
+      "colorToRgba": "Конвертирует именнованный цвет в `rgba` строку.",
+      "getStateMaskGradientBackground": "Возвращает линейный градиент.",
+      "hookMethods": "useColors хуки.",
+      "useColors": "Возвращает методы и переменные цветового конфигуратора.",
+      "hookVariables": "Переменные хука useColors.",
+      "colors": "Реактивная вычисляемая переменная, где ключами являются названия цветов, а значения это валидные CSS цвета."
     }
   },
   "breakpoints": {

packages/docs/page-config/services/colors-config/examples/change-colors.vue

@@ -1,5 +1,5 @@
 <template>
-  <div class="flex items-center">
+  <div class="flex items-center gap-4">
     <va-button>{{ buttonText }}</va-button>
 
     <va-color-palette

packages/docs/page-config/services/colors-config/examples/css-variable.vue

@@ -6,7 +6,7 @@
       <span class="px-2">Danger</span>
     </div>
 
-    <div class="controls flex items-center mt-2">
+    <div class="controls flex items-center gap-4 mt-2">
       <va-color-palette
         v-model="primaryColor"
         :palette="colorsToChange"

packages/docs/page-config/services/colors-config/index.ts

@@ -1,3 +1,15 @@
+import {
+  colorToRgba,
+  setHSLAColor,
+  getFocusColor,
+  getHoverColor,
+  shiftHSLAColor,
+  getBoxShadowColor,
+  getGradientBackground,
+  getBoxShadowColorFromBg,
+  getStateMaskGradientBackground,
+} from 'vuestic-ui/src/services/color';
+
 const columnsApiTypes = [
   "name",
   { title: "type", type: "code" },
@@ -17,67 +29,148 @@ const columnsApiHookVariables = [
 ];
 
 const tableDataApiTypes = [
+  [
+    "CssColor",
+    "string",
+    "colorsConfig.api.cssColor",
+  ],
+  [
+    "EssentialVariables",
+    "Record<string, CssColor>",
+    "colorsConfig.api.essentialVariables",
+  ],
+  [
+    "ColorVariables",
+    "{ [colorName: string]: CssColor } & EssentialVariables",
+    "colorsConfig.api.colorVariables",
+  ],
   [
     "ColorConfig",
-    "{ [colorName: string]: string; }",
-    "colorsConfig.api.ColorConfig",
+    `{
+      variables: ColorVariables,
+      threshold: number,
+      presets: Record<string, ColorVariables>,
+      currentPresetName: string,
+    }`,
+    "colorsConfig.api.colorConfig",
   ],
-  ["ColorInput", "string", "colorsConfig.api.ColorInput"],
 ];
 
 const tableDataApiMethods = [
   [
     "useColors",
     `() => {
       colors,
+      currentPresetName,
+      presets,
+      applyPreset,
       setColors,
       getColors,
       getColor,
+      getComputedColor,
       getBoxShadowColor,
+      getBoxShadowColorFromBg,
       getHoverColor,
       getFocusColor,
-      getGradientBackground
+      getGradientBackground,
+      getTextColor,
+      shiftHSLAColor,
+      setHSLAColor,
+      colorsToCSSVariable,
+      colorToRgba,
+      getStateMaskGradientBackground,
     }`,
     "colorsConfig.api.useColors",
   ],
 ];
 
 const tableDataApiHookMethods = [
+  [
+    "applyPreset",
+    "(presetName: string) => void",
+    "colorsConfig.api.applyPreset",
+  ],
   [
     "setColors",
-    "(colors: Record<string, string>) => void",
+    "(colors: Partial<ColorVariables>) => void",
     "colorsConfig.api.setColors",
   ],
-  ["getColors", "() => ColorConfig", "colorsConfig.api.getColors"],
+  [
+    "getColors",
+    "() => ColorVariables",
+    "colorsConfig.api.getColors",
+  ],
   [
     "getColor",
-    "(prop?: string | undefined, defaultColor?: string) => string",
+    "(prop?: string, defaultColor?: string, preferVariables?: boolean) => CssColor",
     "colorsConfig.api.getColor",
   ],
+  [
+    "getComputedColor",
+    "(color: string) => ComputedRef(CssColor)",
+    "colorsConfig.api.getComputedColor",
+  ],
   [
     "getBoxShadowColor",
-    "(color: ColorInput) => string",
+    "(color: ColorInput, opacity = 0.4) => string",
     "colorsConfig.api.getBoxShadowColor",
   ],
+  [
+    "getBoxShadowColorFromBg",
+    "(background: ColorInput, opacity = 0.4) => string",
+    "colorsConfig.api.getBoxShadowColorFromBg",
+  ],
   [
     "getHoverColor",
-    "(color: ColorInput) => string",
+    "(color: ColorInput, opacity = 0.2) => string",
     "colorsConfig.api.getHoverColor",
   ],
   [
     "getFocusColor",
-    "(color: ColorInput) => string",
+    "(color: ColorInput, opacity = 0.3) => string",
     "colorsConfig.api.getFocusColor",
   ],
   [
     "getGradientBackground",
     "(color: string) => string",
     "colorsConfig.api.getGradientBackground",
   ],
+  [
+    "getTextColor",
+    "(color: ColorInput, darkColor?: string, lightColor?: string) => string",
+    "colorsConfig.api.getTextColor",
+  ],
+  [
+    "shiftHSLAColor",
+    "(color: ColorInput, offset: { h?: number; s?: number; l?: number; a?: number }) => string",
+    "colorsConfig.api.shiftHSLAColor",
+  ],
+  [
+    "setHSLAColor",
+    "(color: ColorInput, newColor: { h?: number; s?: number; l?: number; a?: number }) => string",
+    "colorsConfig.api.setHSLAColor",
+  ],
+  [
+    "colorsToCSSVariable",
+    "(colors: { [colorName: string]: string | undefined }, prefix = 'va') => Record<string, string>",
+    "colorsConfig.api.colorsToCSSVariable",
+  ],
+  [
+    "colorToRgba",
+    "(color: string, maskColor: string, maskOpacity: number) => string",
+    "colorsConfig.api.colorToRgba",
+  ],
+  [
+    "getStateMaskGradientBackground",
+    "(color: string, maskColor: string, maskOpacity: number) => string",
+    "colorsConfig.api.getStateMaskGradientBackground",
+  ],
 ];
 
 const tableDataApiHookVariables = [
-  ["colors", "ColorConfig", "colorsConfig.api.colors"],
+  ["colors", "ColorVariables", "colorsConfig.api.colors"],
+  ["currentPresetName", "ComputedRef<string>", "colorsConfig.api.colors"],
+  ["presets", "ComputedRef<Record<string, ColorVariables>>", "colorsConfig.api.colors"],
 ];
 
 export default definePageConfig({