feat(styles): allow extending theme tokens (#4813)

Author: zettca

packages/styles/src/index.ts

@@ -7,7 +7,13 @@ export * from "./types";
 export * from "./theme";
 export * from "./makeTheme";
 export * from "./utils";
-export * from "./tokens";
+export * from "./tokens/breakpoints";
+export * from "./tokens/colors";
+export * from "./tokens/radii";
+export * from "./tokens/space";
+export * from "./tokens/sizes";
+export * from "./tokens/typography";
+export * from "./tokens/zIndices";
 export * from "./CssBaseline";
 
 // Export each theme individually and a bundle of themes

packages/styles/src/makeTheme.ts

@@ -1,7 +1,7 @@
 import { HvTheme, theme } from "./theme";
-import * as tokens from "./tokens";
-import { colors, type ColorTokens } from "./tokens";
-import type { HvCustomTheme, HvThemeColors, HvThemeStructure } from "./types";
+import { baseTheme } from "./tokens";
+import { colors, HvThemeColors, type ColorTokens } from "./tokens/colors";
+import type { HvCustomTheme, HvThemeStructure } from "./types";
 import { mergeTheme } from "./utils";
 
 /**
@@ -15,7 +15,7 @@ export const makeTheme = <Mode extends string = string>(
   options: HvCustomTheme<Mode> | ((theme: HvTheme) => HvCustomTheme<Mode>),
 ): HvThemeStructure<Mode> => {
   const customTheme = typeof options === "function" ? options(theme) : options;
-  const newTheme = mergeTheme(tokens, customTheme);
+  const newTheme = mergeTheme(baseTheme, customTheme);
 
   return newTheme;
 };

packages/styles/src/theme.ts

@@ -1,6 +1,6 @@
 import { palette } from "./palette";
-import * as tokens from "./tokens";
-import type { HvColor, HvColorAny } from "./tokens";
+import { baseTheme as tokens } from "./tokens";
+import type { HvColor, HvColorAny } from "./tokens/colors";
 import {
   DeepString,
   HvThemeComponents,

packages/styles/src/themes/pentahoPlus.ts

@@ -13,7 +13,6 @@ import {
   slate,
   yellow,
 } from "../palette";
-import { radii } from "../tokens";
 
 const pentahoPlus = makeTheme((theme) => ({
   name: "pentahoPlus",
@@ -256,7 +255,6 @@ const pentahoPlus = makeTheme((theme) => ({
     xl: "64px",
   },
   radii: {
-    ...radii,
     base: "4px",
     round: "8px",
     large: "16px",

packages/styles/src/tokens/breakpoints.ts

@@ -1,3 +1,12 @@
+export type HvBreakpoints = "xs" | "sm" | "md" | "lg" | "xl";
+
+/** @experimental extendable theme breakpoints */
+export interface HvThemeBreakpoints {
+  unit: string;
+  step: number;
+  values: Record<HvBreakpoints, number>;
+}
+
 export const breakpoints = {
   unit: "px",
   step: 5,
@@ -8,6 +17,4 @@ export const breakpoints = {
     lg: 1270,
     xl: 1920,
   },
-};
-
-export type HvBreakpoints = keyof typeof breakpoints.values;
+} satisfies HvThemeBreakpoints;

packages/styles/src/tokens/colors.ts

@@ -203,9 +203,18 @@ const categorical = {
   cat28: "#D8265D",
 };
 
+const support = {
+  supp1: "#0F8B8D",
+  supp2: "#734B6D",
+  supp3: "#4E7599",
+  supp4: "#C19C31",
+  supp5: "#546B6B",
+};
+
 const common = {
   ...base,
   ...categorical,
+  ...support,
 };
 
 // #region Light palette
@@ -255,14 +264,6 @@ const semanticLight = {
   warning_20: "#FBF2D8",
 };
 
-const supportLight = {
-  supp1: "#0F8B8D",
-  supp2: "#734B6D",
-  supp3: "#4E7599",
-  supp4: "#C19C31",
-  supp5: "#546B6B",
-};
-
 const shadowLight = {
   shad1: "rgba(65, 65, 65, 0.12)",
   shadow: "0 2px 12px rgba(65,65,65,0.12)",
@@ -382,14 +383,6 @@ const semanticDark = {
   warning_20: "#FBF2D8",
 };
 
-const supportDark = {
-  supp2: "#734B6D",
-  supp3: "#4E7599",
-  supp4: "#C19C31",
-  supp5: "#546B6B",
-  supp1: "#0F8B8D",
-};
-
 const shadowDark = {
   shad1: "rgba(0,0,0,.16)",
   shadow: "0 3px 5px rgba(0,0,0,.16)",
@@ -466,7 +459,6 @@ export const colors = {
     ...accentLight,
     ...atmosphereLight,
     ...semanticLight,
-    ...supportLight,
     ...shadowLight,
     ...utilsLight,
     ...newLight,
@@ -475,23 +467,28 @@ export const colors = {
     ...accentDark,
     ...atmosphereDark,
     ...semanticDark,
-    ...supportDark,
     ...shadowDark,
     ...utilsDark,
     ...newDark,
   },
 };
 
-// TODO: remove in favour of `HvColor`/`HvColorAny`?
+/** @deprecated replace with standard UI Kit ColorTokens in v6 */
+type AllColors = typeof colors.common & typeof colors.light;
+
+/** @experimental extendable theme colors */
+export interface HvThemeColors extends ColorTokens, AllColors {}
+
+// TODO: remove in favour of `HvColor`/`HvColorAny`
 export type HvAccentColor = keyof typeof accentLight;
 export type HvAtmosphereColor = keyof typeof atmosphereLight;
 export type HvBaseColor = keyof typeof base;
 export type HvSemanticColor = keyof typeof semanticLight;
-export type HvSupportColor = keyof typeof supportLight;
+export type HvSupportColor = keyof typeof support;
 export type HvCategoricalColor = keyof typeof categorical;
 
 /** A type with all the accepted colors from the color palette */
-export type HvColor = keyof typeof colors.common | keyof typeof colors.light;
+export type HvColor = keyof HvThemeColors;
 
 /**
  * A type representing an `HvColor` from the palette or any other color string

packages/styles/src/tokens/index.ts

@@ -1,7 +1,24 @@
-export * from "./breakpoints";
-export * from "./colors";
-export * from "./radii";
-export * from "./space";
-export * from "./sizes";
-export * from "./typography";
-export * from "./zIndices";
+import { breakpoints } from "./breakpoints";
+import { colors } from "./colors";
+import { radii } from "./radii";
+import { sizes } from "./sizes";
+import { space } from "./space";
+import { fontFamily, fontSizes, fontWeights, lineHeights } from "./typography";
+import { zIndices } from "./zIndices";
+
+/**
+ * Base theme tokens to use when merging with theme, used to merge with the makeTheme utility.
+ * Mostly just the uses the `tokens` directly, but also adds other properties like `typography` or component vars.
+ */
+export const baseTheme = {
+  breakpoints,
+  colors,
+  radii,
+  space,
+  sizes,
+  zIndices,
+  fontFamily,
+  fontSizes,
+  fontWeights,
+  lineHeights,
+};

packages/styles/src/tokens/radii.ts

@@ -1,4 +1,9 @@
-export const radii = {
+export type HvRadius = "none" | "base" | "round" | "large" | "circle" | "full";
+
+/** @experimental */
+export interface HvThemeRadii extends Record<HvRadius, string> {}
+
+export const radii: HvThemeRadii = {
   none: "0px",
   base: "2px",
   round: "6px",
@@ -7,5 +12,3 @@ export const radii = {
   circle: "50%",
   full: "9999px",
 };
-
-export type HvRadius = keyof typeof radii;

packages/styles/src/tokens/space.ts

@@ -1,4 +1,11 @@
-export const space = {
+type HvSpace = "xxs" | "xs" | "sm" | "md" | "lg" | "xl";
+
+/** @experimental extendable theme spacing units */
+export interface HvThemeSpace extends Record<HvSpace, string> {
+  base: number;
+}
+
+export const space: HvThemeSpace = {
   base: 8,
   xxs: "4px",
   xs: "8px",

packages/styles/src/types.ts

@@ -1,22 +1,40 @@
 import type { StandardProperties } from "csstype";
 
-import * as tokens from "./tokens";
-import { colors } from "./tokens/colors";
-
-// Theme tokens
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-const flattenTokens = {
-  ...tokens,
-  colors: {
-    type: "light",
-    ...tokens.colors.common,
-    ...tokens.colors.light,
-  },
-};
+import type { HvThemeBreakpoints } from "./tokens/breakpoints";
+import type { HvThemeColors } from "./tokens/colors";
+import type { HvThemeRadii } from "./tokens/radii";
+import { sizes } from "./tokens/sizes";
+import { HvThemeSpace, space } from "./tokens/space";
+import {
+  fontFamily,
+  fontSizes,
+  fontWeights,
+  lineHeights,
+} from "./tokens/typography";
+import { zIndices } from "./tokens/zIndices";
 
 interface CSSProperties extends StandardProperties<string | number> {}
 
-export type HvThemeTokens = typeof flattenTokens;
+/** @experimental extendable theme spacing units */
+export interface HvThemeZIndices
+  extends Record<keyof typeof zIndices, number> {}
+
+/** UI Kit static theme tokens */
+export interface HvThemeTokens {
+  breakpoints: HvThemeBreakpoints;
+  colors: { type: HvThemeColorModeType } & HvThemeColors;
+  radii: HvThemeRadii;
+  space: HvThemeSpace;
+  /** @deprecated use `theme.space` or the direct value instead */
+  sizes: typeof sizes;
+  // #region typography
+  fontFamily: typeof fontFamily;
+  fontSizes: typeof fontSizes;
+  fontWeights: typeof fontWeights;
+  lineHeights: typeof lineHeights;
+  // #endregion
+  zIndices: HvThemeZIndices;
+}
 
 /** Theme components props */
 export interface HvThemeComponentsProps {
@@ -68,7 +86,7 @@ export interface HvThemeComponents {
 }
 
 // Theme typography
-// TODO: allow arbitrary `CSSProperties` overrides
+// TODO: remove in favor of `CSSProperties` when supported
 export interface HvThemeTypographyProps
   extends Pick<
     CSSProperties,
@@ -98,13 +116,10 @@ export interface HvThemeTypography {
 }
 
 // Breakpoints
-export type HvThemeBreakpoint = Exclude<keyof typeof tokens.space, "base">;
+export type HvThemeBreakpoint = Exclude<keyof typeof space, "base">;
 
 export type SpacingValue = number | HvThemeBreakpoint | (string & {});
 
-// Theme colors
-export type HvThemeColors = typeof colors.common & typeof colors.light;
-
 // Base themes: DS3 and DS5
 export type HvBaseTheme = "ds3" | "ds5" | "pentahoPlus";
 
@@ -121,7 +136,7 @@ export interface HvThemeColorModeStructure
   type: HvThemeColorModeType;
 }
 
-// Theme structure
+/** Complete theme structure and values */
 export interface HvThemeStructure<Mode extends string = string>
   extends HvThemeComponents,
     HvThemeComponentsProps,
@@ -136,21 +151,17 @@ export interface HvThemeStructure<Mode extends string = string>
 
 // Custom theme
 export interface HvCustomTheme<Mode extends string = string>
-  extends HvThemeComponents,
-    HvThemeComponentsProps,
-    HvThemeTypography,
-    Partial<Omit<HvThemeTokens, "colors">> {
-  name: string;
-  colors: {
-    modes: Record<Mode, Partial<HvThemeColorModeStructure>>;
-  };
-}
+  extends DeepPartial<Omit<HvThemeStructure<Mode>, "base">> {}
 
 // Deep string: set all props to strings
 export type DeepString<T> = {
   [P in keyof T]: T[P] extends object ? DeepString<T[P]> : string;
 };
 
+type DeepPartial<T> = T extends {}
+  ? Partial<{ [P in keyof T]: DeepPartial<T[P]> }>
+  : T;
+
 // Theme CSS vars
 export interface HvThemeVars
   extends DeepString<HvThemeTokens>,