feat: ts types for colors (#3957) (#4270)

packages/docs/page-config/services/colors-config/code/color-typings-augmentation.ts

@@ -0,0 +1,5 @@
+declare module 'vuestic-ui' {
+  interface CustomColorVariables {
+    newColor: string
+  }
+}

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

@@ -147,14 +147,18 @@ export default definePageConfig({
     block.paragraph("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
-    block.subtitle("Colors config with other services"),
+    block.subtitle("Adding new colors"),
 
-    block.paragraph("You can use your custom colors in Components config."),
+    block.paragraph("You can add new colors and use your custom colors in Components config."),
     block.code("components-config"),
 
-    block.paragraph("As well as in Icons config."),
+    block.paragraph("The same works for Icons config."),
     block.code("icons-config"),
 
+    block.subtitle("Getting typings for custom colors"),
+    block.paragraph("Color config is fully typed and provides type safety and autocompletion for all instances where color is specified. Color typings could be extended with your custom colors to rip the same benefits via Typescript [Module augmentation](https://www.typescriptlang.org/docs/handbook/declaration-merging.html#module-augmentation)."),
+    block.code("color-typings-augmentation"),
+
     // api
     block.subtitle("Colors config service API"),
 

packages/ui/src/main.ts

@@ -27,5 +27,5 @@ export { defineVuesticConfig } from './services/global-config/types'
 export type { GlobalConfig, GlobalConfigUpdater, PartialGlobalConfig } from './services/global-config/types'
 export type { ComponentConfig } from './services/component-config'
 export type { IconConfig, IconConfiguration } from './services/icon/types'
-export type { ColorConfig } from './services/color/types'
+export type { ColorConfig, CustomColorVariables } from './services/color/types'
 export type { I18NKey, I18nConfig, CustomI18NKeys } from './services/i18n'

packages/ui/src/services/color/types.ts

@@ -25,14 +25,31 @@ export type EssentialVariables = {
   transparent: CssColor,
 }
 
+/**
+ * This is a placeholder meant to be implemented via TypeScript's Module
+ * Augmentation feature to allow key type inference
+ *
+ * @example
+ * ```ts
+ * declare module 'vuestic-ui' {
+ *   interface CustomColorVariables {
+ *     newColor: string
+ *   }
+ * }
+ * ```
+ *
+ * @see https://www.typescriptlang.org/docs/handbook/declaration-merging.html#module-augmentation
+ */
+export interface CustomColorVariables {}
+
 type Capitalize<S extends string> = S extends `${infer First}${infer Rest}`
   ? `${Uppercase<First>}${Rest}`
   : S
-type OnColors = `on${Capitalize<keyof EssentialVariables>}`
+type OnColors = `on${Capitalize<keyof EssentialVariables | keyof CustomColorVariables>}`
 
-export type ColorVariables = { [colorName: string]: CssColor } & EssentialVariables & {
+export type ColorVariables = EssentialVariables & CustomColorVariables & {
   [key in OnColors]?: CssColor
-}
+} & Record<string, CssColor>
 
 export type ColorConfig = {
   variables: ColorVariables,

packages/ui/src/services/global-config/types.ts

@@ -1,8 +1,8 @@
 import type { ComponentConfig } from '../component-config'
-import type { ColorConfig } from '../color'
+import type { ColorConfig, CustomColorVariables } from '../color'
 import type { IconConfig } from '../icon'
 import type { BreakpointConfig } from '../breakpoint'
-import type { I18nConfig } from '../i18n'
+import type { I18nConfig, CustomI18NKeys } from '../i18n'
 import type { Ref, Component } from 'vue'
 import type { ColorsClassesConfig } from '../colors-classes'
 
@@ -21,7 +21,13 @@ type DeepPartial<T> = T extends Record<string, any> ? {
   [P in keyof T]?: P extends 'components' ? T[P] : DeepPartial<T[P]>;
 } : T;
 
-export type PartialGlobalConfig = DeepPartial<GlobalConfig>
+export type PartialGlobalConfig = DeepPartial<GlobalConfig> & {
+  // Need to maintain ability to extend through module augmentation
+  colors?: {
+    variables?: Partial<CustomColorVariables>
+  }
+  i18n?: Partial<CustomI18NKeys>
+}
 
 export type SizeConfig = {
   defaultSize?: number,