fix(types): improve Root Provider theme type definitions and docs

Author: morewings

README.md

@@ -168,15 +168,28 @@ The reason this code isn’t correct is that it tries to do something with the D
 
 ### Type safety
 
-Global theme type should be defined on a project level. You'll have to redeclare `ThemeType` export from `css-vars-hook`
+Developers can provide theme type to `useRootTheme` hook as a TypeScript Generic.
 
-```ts
-// types.d.ts
-import theme from '@/theme';
+```tsx
+import { FC } from "react";
+
+type Theme = {
+    boxColor: 'yellow' | 'blue';
+    borderColor: string;
+};
+
+const themeYellow: Theme = {
+    boxColor: 'yellow',
+    borderColor: 'blue',
+};
 
-declare module 'css-vars-hook' {
-    // Provide your global theme type here
-    export type ThemeType = typeof theme;
+const Component: FC = () => {
+    const {setTheme, getTheme, setVariable} = useRootTheme<Theme>();
+    const doSomething = () => {
+        // theme value will be properly typed this way
+        console.log('root theme', getTheme().boxColor);
+    };
+    //...
 }
 ```
 

src/env/examples/Root/Root.tsx

@@ -4,20 +4,25 @@ import {useRootTheme} from '@/lib';
 
 import classes from './Root.module.css';
 
-const themeYellow = {
+type Theme = {
+    boxColor: string;
+    borderColor: string;
+};
+
+const themeYellow: Theme = {
     boxColor: 'yellow',
     borderColor: 'blue',
 };
 
-const themePink = {
+const themePink: Theme = {
     boxColor: 'pink',
     borderColor: 'brown',
 };
 
 let renderCount = 0;
 
 export const Root = () => {
-    const {setTheme, getTheme, setVariable} = useRootTheme();
+    const {setTheme, getTheme, setVariable} = useRootTheme<Theme>();
 
     const setThemePink = () => {
         setTheme(themePink);

src/lib/RootTheme/HookInterfaceType.ts

@@ -1,12 +1,12 @@
-import type {UnitType, Theme} from '@/lib/ThemeType.ts';
+import type {UnitType} from '@/lib/ThemeType.ts';
 
 /**
  * @public
  * `useRootTheme` return type.
  */
-export type HookInterface = {
-    setTheme: (nextTheme: Theme) => void;
-    getTheme: () => Theme;
+export type HookInterface<TTheme> = {
+    setTheme: (nextTheme: TTheme) => void;
+    getTheme: () => TTheme;
     setVariable: (variableName: string, value: UnitType) => void;
     getVariable: (variableName: string) => string;
     removeVariable: (variableName: string) => void;

src/lib/RootTheme/RootContext.ts

@@ -1,13 +1,19 @@
+import type {Context} from 'react';
 import {useContext, createContext} from 'react';
 
+import type {Theme} from '@/lib/ThemeType.ts';
+
 import type {HookInterface} from './HookInterfaceType';
 
-export const RootContext = createContext<HookInterface>({
+export const RootContext = createContext({
     setTheme: () => {},
     getTheme: () => ({}),
     setVariable: () => {},
     getVariable: () => '',
     removeVariable: () => {},
-});
+} as HookInterface<Theme>);
 
-export const useRootContext = () => useContext<HookInterface>(RootContext);
+export const useRootContext = <TTheme extends Theme>() =>
+    useContext<HookInterface<TTheme>>(
+        RootContext as unknown as Context<HookInterface<TTheme>>
+    );

src/lib/RootTheme/useRootTheme.ts

@@ -16,14 +16,14 @@ import type {HookInterface} from './HookInterfaceType';
  * @private
  * Logic for root theme handling such as updates and CSS style creation
  */
-export const useRootTheme = (
-    theme: Theme,
+export const useRootTheme = <TTheme extends Theme>(
+    theme: TTheme,
     id: string
-): HookInterface & {style: CSSProperties} => {
+): HookInterface<TTheme> & {style: CSSProperties} => {
     const themeRef = useRef(theme);
 
     const setTheme = useCallback(
-        (nextTheme: Theme) => {
+        (nextTheme: TTheme) => {
             setRootTheme(id)(nextTheme);
             themeRef.current = nextTheme;
         },

src/lib/RootTheme/useRootThemePublic.ts

@@ -1,3 +1,5 @@
+import type {Theme} from '@/lib/ThemeType.ts';
+
 import {useRootContext} from './RootContext';
 
 /**
@@ -7,9 +9,9 @@ import {useRootContext} from './RootContext';
  * @see ThemeType
  * @see https://github.com/morewings/css-vars-hook#type-safety
  */
-export const useRootThemePublic = () => {
+export const useRootThemePublic = <TTheme extends Theme>() => {
     const {setTheme, getTheme, setVariable, getVariable, removeVariable} =
-        useRootContext();
+        useRootContext<TTheme>();
     return {
         /** Effect to apply new theme to the application */
         setTheme,