[WB-2178.2] NodeIconButton: Add tokens prop (#2905)

## Summary:

Next part of the new `NodeIconButton` component. This PR adds the `tokens` prop
to support overriding component-level tokens.

The tokens type was updated to be able to define and pass the tokens in a more
flexible way.


## Implementation

1. #2897
2. #2905


Issue: WB-2178

## Test plan:

Navigate to
`/?path=/docs/packages-iconbutton-nodeiconbutton--docs&globals=theme:thunderblocks#with-custom-tokens`
and verify that the tokens are working as expected.

Author: jandrade

Reviewers: beaesguerra, jandrade

Required Reviewers:

Approved By: beaesguerra

Checks: ✅ 13 checks were successful, ⏭️  3 checks have been skipped

Pull Request URL: #2905

Author: jandrade

.changeset/afraid-pants-tease.md

@@ -0,0 +1,5 @@
+---
+"@khanacademy/wonder-blocks-icon-button": minor
+---
+
+NodeIconButton: Adds a new `tokens` prop to support overriding component-level tokens

__docs__/wonder-blocks-icon-button/node-icon-button.stories.tsx

@@ -195,13 +195,66 @@ export const WithCustomIcon: StoryComponentType = {
 };
 
 /**
- * You can use the `styles` prop to apply custom styles to speicific parts of
- * the `NodeIconButton` component.
+ * The recommended way to customize the appearance of the `NodeIconButton`
+ * component is to use the `tokens` prop. This prop accepts a token object that
+ * contains the CSS variables that can be overridden to customize the appearance
+ * of the `NodeIconButton` component.
+ *
+ * The following tokens can be overridden:
+ * - `boxForeground`: The foreground color of the "chonky" box element.
+ * - `boxBackground`: The background color of the "chonky" box element.
+ * - `boxShadowColor`: The color of the shadow of the "chonky" box element.
+ * - `boxPadding`: The padding of the "chonky" box element.
+ * - `boxShadowYRest`: The y-offset of the rest state shadow of the "chonky" box
+ *   element.
+ * - `boxShadowYHover`: The y-offset of the hover state shadow of the "chonky"
+ *   box element.
+ * - `boxShadowYPress`: The y-offset of the press state shadow of the "chonky"
+ *   box element.
+ * - `iconSize`: The size of the icon element.
+ */
+export const WithCustomTokens: StoryComponentType = {
+    render: () => {
+        return (
+            <NodeIconButton
+                icon={IconMappings.info}
+                aria-label="More information"
+                tokens={{
+                    boxForeground:
+                        semanticColor.learning.foreground.streaks.default,
+                    boxBackground:
+                        semanticColor.learning.background.streaks.default,
+                    boxShadowColor: semanticColor.learning.math.foreground.pink,
+                    boxPadding: sizing.size_120,
+                    boxShadowYRest: sizing.size_080,
+                    boxShadowYHover: sizing.size_100,
+                    boxShadowYPress: sizing.size_0,
+                    iconSize: sizing.size_960,
+                }}
+            />
+        );
+    },
+    parameters: {
+        chromatic: {
+            // Keep snapshots to confirm token overrides are working
+            disableSnapshot: false,
+        },
+    },
+};
+
+/**
+ * Alternatively, you can use the `styles` prop to apply custom styles to
+ * speicific parts of the `NodeIconButton` component.
  *
  * The following parts can be styled:
  * - `root`: Styles the root element (button)
  * - `box`: Styles the "chonky" box element
  * - `icon`: Styles the icon element
+ *
+ * **Note:** The `styles` prop is not recommended for most use cases. Instead,
+ * we recommend using the `tokens` prop to customize the appearance of the
+ * `NodeIconButton` component. If you still need to provide more specific
+ * styles, you can use the `styles` prop.
  */
 export const WithCustomStyles: StoryComponentType = {
     render: () => {

packages/wonder-blocks-icon-button/src/components/node-icon-button.tsx

@@ -10,12 +10,20 @@ import {border, semanticColor, sizing} from "@khanacademy/wonder-blocks-tokens";
 import type {BaseIconButtonProps} from "../util/icon-button.types";
 
 import {IconButtonUnstyled} from "./icon-button-unstyled";
+import {mapTokensToVariables} from "../util/map-tokens-to-variables";
 
 /**
- * The object containing the CSS variables that can be overridden to customize
- * the appearance of the NodeIconButton component.
+ * The prefix for the CSS variables used in the NodeIconButton component.
+ *
+ * This allows us to avoid collisions with other CSS variables in the
+ * application.
  */
-type Tokens = Partial<{
+const VAR_PREFIX = "--wb-c-node-icon-button--";
+
+/**
+ * The valid component-level tokens for the NodeIconButton component.
+ */
+type Tokens = {
     "--wb-c-node-icon-button--box-foreground": string;
     "--wb-c-node-icon-button--box-background": string;
     "--wb-c-node-icon-button--box-shadow-color": string;
@@ -24,16 +32,33 @@ type Tokens = Partial<{
     "--wb-c-node-icon-button--box-shadow-y-hover": string | number;
     "--wb-c-node-icon-button--box-shadow-y-press": string | number;
     "--wb-c-node-icon-button--icon-size": string | number;
-}>;
+};
+
+/**
+ * The default tokens that are assigned to the root element.
+ *
+ * These tokens could be overridden by baked-in variants and/or the `tokens`
+ * prop.
+ */
+const DEFAULT_TOKENS: Tokens = {
+    "--wb-c-node-icon-button--box-padding": sizing.size_100,
+    "--wb-c-node-icon-button--box-shadow-y-rest": "6px",
+    "--wb-c-node-icon-button--box-shadow-y-hover": "8px",
+    "--wb-c-node-icon-button--box-shadow-y-press": sizing.size_0,
+    "--wb-c-node-icon-button--icon-size": sizing.size_480,
+    "--wb-c-node-icon-button--box-foreground":
+        semanticColor.learning.foreground.progress.notStarted.strong,
+    "--wb-c-node-icon-button--box-background":
+        semanticColor.learning.background.progress.notStarted.default,
+    "--wb-c-node-icon-button--box-shadow-color":
+        semanticColor.learning.shadow.progress.notStarted.default,
+};
 
 type Props = Omit<BaseIconButtonProps, "kind" | "style"> & {
     /**
      * The action type of the button. This determines the visual style of
      * the button. Defaults to `notStarted`.
      *
-     * - `notStarted` is used for buttons that indicate a not started action.
-     * - `attempted` is used for buttons that indicate an attempted (in progress)
-     *   action.
      * - `complete` is used for buttons that indicate a complete action.
      */
     actionType?: "notStarted" | "attempted" | "complete";
@@ -60,11 +85,26 @@ type Props = Omit<BaseIconButtonProps, "kind" | "style"> & {
         box?: StyleType;
         icon?: StyleType;
     };
+
+    /**
+     * The token object that contains the CSS variables that can be overridden
+     * to customize the appearance of the NodeIconButton component.
+     */
+    tokens?: {
+        boxForeground?: string;
+        boxBackground?: string;
+        boxShadowColor?: string;
+        boxPadding?: string | number;
+        boxShadowYRest?: string | number;
+        boxShadowYHover?: string | number;
+        boxShadowYPress?: string | number;
+        iconSize?: string | number;
+    };
 };
 
 /**
  * Node buttons are visual representations of activities along in a Learning
- * Path. When a represented No  de is a button that launches the activity. Nodes
+ * Path. When a represented Node is a button that launches the activity. Nodes
  * use the Chonky shadow style.
  *
  * ```tsx
@@ -91,6 +131,7 @@ export const NodeIconButton: React.ForwardRefExoticComponent<
         icon,
         size = "large",
         styles: stylesProp,
+        tokens,
         type = "button",
         // labeling
         "aria-label": ariaLabel,
@@ -99,14 +140,19 @@ export const NodeIconButton: React.ForwardRefExoticComponent<
 
     const [pressed, setPressed] = React.useState(false);
 
-    const buttonStyles = [
-        styles.button,
-        disabled && styles.disabled,
-        !disabled && pressed && styles.pressed,
-        variants.size[size] as StyleType,
-        variants.actionType[actionType] as StyleType,
-        stylesProp?.root,
-    ];
+    const buttonStyles = React.useMemo(
+        () => [
+            styles.button,
+            disabled && styles.disabled,
+            !disabled && pressed && styles.pressed,
+            variants.size[size] as StyleType,
+            variants.actionType[actionType] as StyleType,
+            stylesProp?.root,
+            // Token overrides.
+            tokens && mapTokensToVariables(tokens, VAR_PREFIX),
+        ],
+        [actionType, disabled, pressed, size, stylesProp?.root, tokens],
+    );
 
     const chonkyStyles = [
         styles.chonky,
@@ -141,7 +187,7 @@ export const NodeIconButton: React.ForwardRefExoticComponent<
             disabled={disabled}
             onPress={handlePress}
             ref={ref}
-            style={buttonStyles}
+            style={buttonStyles as StyleType}
             type={type}
             aria-label={ariaLabel}
         >
@@ -155,9 +201,13 @@ export const NodeIconButton: React.ForwardRefExoticComponent<
     );
 });
 
+/**
+ * An object containing all the different combinations of tokens for the
+ * NodeIconButton component.
+ */
 const variants: {
-    size: Record<string, Tokens>;
-    actionType: Record<string, Tokens>;
+    size: Record<string, Partial<Tokens>>;
+    actionType: Record<string, Partial<Tokens>>;
 } = {
     size: {
         // Default size.
@@ -235,6 +285,7 @@ const styles = StyleSheet.create({
         alignSelf: "flex-start",
         justifySelf: "center",
         gap: sizing.size_020,
+        ...DEFAULT_TOKENS,
 
         /**
          * States
@@ -268,7 +319,6 @@ const styles = StyleSheet.create({
             ...chonkyDisabled,
             ...disabledStatesStyles,
         },
-        // [":is(:active) .chonky" as any]: chonkyDisabled,
     },
     // Enable keyboard support for press styles.
     pressed: {

packages/wonder-blocks-icon-button/src/util/__tests__/map-tokens-to-variables.test.ts

@@ -0,0 +1,72 @@
+import {
+    mapTokensToVariables,
+    type TokensAsJsVariable,
+} from "../map-tokens-to-variables";
+
+describe("mapTokensToVariables", () => {
+    it("maps camelCase tokens to CSS variable keys with a given prefix", () => {
+        // Arrange
+        const tokens: Partial<
+            TokensAsJsVariable<"boxForeground" | "iconSize">
+        > = {
+            boxForeground: "#fff",
+            iconSize: 24,
+        };
+        const prefix = "--wb-node-icon-button--";
+
+        // Act
+        const result = mapTokensToVariables(tokens, prefix);
+
+        // Assert
+        expect(result).toEqual({
+            "--wb-node-icon-button--box-foreground": "#fff",
+            "--wb-node-icon-button--icon-size": 24,
+        });
+    });
+
+    it("returns an empty object for empty tokens", () => {
+        // Arrange
+        const tokens: Partial<TokensAsJsVariable<"box-background">> = {};
+        const prefix = "--wb-node-icon-button--";
+
+        // Act
+        const result = mapTokensToVariables(tokens, prefix);
+
+        // Assert
+        expect(result).toEqual({});
+    });
+
+    it("handles boolean and number values correctly", () => {
+        // Arrange
+        const tokens: Partial<TokensAsJsVariable<"boxShadow" | "isActive">> = {
+            boxShadow: 10,
+            isActive: false,
+        };
+        const prefix = "--custom-";
+
+        // Act
+        const result = mapTokensToVariables(tokens, prefix);
+
+        // Assert
+        expect(result).toEqual({
+            "--custom-box-shadow": 10,
+            "--custom-is-active": false,
+        });
+    });
+
+    it("preserves only properties present on the tokens object", () => {
+        // Arrange
+        const tokens: Partial<TokensAsJsVariable<"a" | "b" | "c">> = {
+            a: 1,
+        };
+        const prefix = "--x-";
+
+        // Act
+        const result = mapTokensToVariables(tokens, prefix);
+
+        // Assert
+        expect(result).toEqual({
+            "--x-a": 1,
+        });
+    });
+});

packages/wonder-blocks-icon-button/src/util/map-tokens-to-variables.ts

@@ -0,0 +1,61 @@
+type TokenValue = string | number;
+
+/**
+ * Converts a kebab-case string to a camelCase string.
+ *
+ * @example
+ * type CamelCaseString = KebabToCamelCase<"box-foreground">;
+ * // CamelCaseString = "boxForeground";
+ */
+type KebabToCamelCase<S extends string> = S extends `${infer T}-${infer U}`
+    ? `${T}${Capitalize<KebabToCamelCase<U>>}`
+    : S;
+
+/**
+ * The type containing the keys using the camelCase format.
+ *
+ * @example
+ * type TokensAsJsVariable = {
+ *     boxForeground: string;
+ */
+export type TokensAsJsVariable<K extends string> = {
+    [key in KebabToCamelCase<K>]: string | number | boolean;
+};
+
+/**
+ * The type containing the CSS variables that can be overridden to customize the
+ * appearance of a component.
+ *
+ * @example
+ * const tokens: TokensAsVariable<ComponentTokensPrefix> = {
+ *     "--wb-c-node-icon-button--box-foreground": "red",
+ * };
+ */
+type TokensAsCssVariable<T extends string, K extends string> = {
+    [key in `${T}${K}`]: TokenValue;
+};
+
+/**
+ * Maps a object of camel-cased tokens to a object of kebab-cased CSS variables.
+ *
+ * @param tokens The object of camel-cased tokens to map.
+ * @param prefix The prefix to use for the CSS variables.
+ * @returns The object of kebab-cased CSS variables.
+ */
+export function mapTokensToVariables<T extends string, P extends string>(
+    tokens: Partial<TokensAsJsVariable<T>>,
+    prefix: P,
+) {
+    // Only pass the keys that are included in the object.
+    return Object.entries(tokens).reduce(
+        (acc, [key, value]) => {
+            // Convert camelCase key to kebab-case.
+            const kebabKey = key.replace(/([A-Z])/g, "-$1").toLowerCase();
+
+            acc[`${prefix}${kebabKey}` as keyof TokensAsCssVariable<P, T>] =
+                value as TokenValue;
+            return acc;
+        },
+        {} as Record<keyof TokensAsCssVariable<P, T>, TokenValue>,
+    );
+}