feat(tooltip): add keyboard shortcuts to tooltip

.changeset/happy-panthers-buy.md

@@ -0,0 +1,6 @@
+---
+"@twilio-paste/tooltip": minor
+"@twilio-paste/core": minor
+---
+
+[Tooltip] added the ability to put keyboard combinations using the KeyboardKey in the tooltip

packages/paste-core/components/code-block/package.json

@@ -36,6 +36,7 @@
     "@twilio-paste/flex": "^8.0.0",
     "@twilio-paste/heading": "^11.0.0",
     "@twilio-paste/icons": "^12.0.0",
+    "@twilio-paste/keyboard-key": "^0.0.0",
     "@twilio-paste/reakit-library": "^2.0.0",
     "@twilio-paste/screen-reader-only": "^13.0.0",
     "@twilio-paste/spinner": "^14.0.0",
@@ -68,6 +69,7 @@
     "@twilio-paste/flex": "^8.1.0",
     "@twilio-paste/heading": "^11.1.0",
     "@twilio-paste/icons": "^12.2.0",
+    "@twilio-paste/keyboard-key": "^0.0.0",
     "@twilio-paste/reakit-library": "^2.1.1",
     "@twilio-paste/screen-reader-only": "^13.1.0",
     "@twilio-paste/spinner": "^14.1.2",

packages/paste-core/components/tooltip/package.json

@@ -31,8 +31,10 @@
     "@twilio-paste/customization": "^8.0.0",
     "@twilio-paste/design-tokens": "^10.0.0",
     "@twilio-paste/icons": "^12.0.0",
+    "@twilio-paste/keyboard-key": "^0.0.0",
     "@twilio-paste/reakit-library": "^2.0.0",
     "@twilio-paste/spinner": "^14.0.0",
+    "@twilio-paste/stack": "^8.1.0",
     "@twilio-paste/style-props": "^9.0.0",
     "@twilio-paste/styling-library": "^3.0.0",
     "@twilio-paste/text": "^10.0.0",
@@ -52,8 +54,10 @@
     "@twilio-paste/customization": "^8.1.0",
     "@twilio-paste/design-tokens": "^10.2.0",
     "@twilio-paste/icons": "^12.2.0",
+    "@twilio-paste/keyboard-key": "^0.0.0",
     "@twilio-paste/reakit-library": "^2.1.0",
     "@twilio-paste/spinner": "^14.1.0",
+    "@twilio-paste/stack": "^8.1.0",
     "@twilio-paste/style-props": "^9.1.0",
     "@twilio-paste/styling-library": "^3.0.0",
     "@twilio-paste/text": "^10.1.0",

packages/paste-core/components/tooltip/src/Tooltip.tsx

@@ -1,5 +1,7 @@
 import { Box, safelySpreadBoxProps } from "@twilio-paste/box";
 import type { BoxProps } from "@twilio-paste/box";
+import { KeyboardKey, KeyboardKeyGroup } from "@twilio-paste/keyboard-key";
+import { Stack } from "@twilio-paste/stack";
 import { Text } from "@twilio-paste/text";
 import { StyledBase } from "@twilio-paste/theme";
 import { TooltipPrimitive, TooltipPrimitiveReference, useTooltipPrimitiveState } from "@twilio-paste/tooltip-primitive";
@@ -60,42 +62,111 @@ export interface TooltipProps extends TooltipPrimitiveInitialState {
    * @memberof TooltipProps
    */
   text: string;
+  actionHeader?: never;
+  keyCombinationsActions?: never;
 }
 
+interface KeyboardActions {
+  name: string;
+  eventKeyCombination: string[];
+  disabled?: boolean;
+}
+
+export interface KeyboardKeyTooltipProps
+  extends Omit<TooltipProps, "text" | "keyCombinationsActions" | "actionHeader"> {
+  text?: never;
+  /**
+   * The mapping of action names to their respective key combinations.
+   *
+   * @type {Array<KeyboardActions>}
+   * @memberof KeyboardKeyTooltipProps
+   */
+  keyCombinationsActions: Array<KeyboardActions>;
+  /**
+   * The header content of the Tooltip.
+   *
+   * @type {string}
+   * @memberof KeyboardKeyTooltipProps
+   */
+  actionHeader?: string;
+}
+
+// Union will stop users from adding types from both TooltipProps and KeyboardKeyTooltipProps at the same time.
+export type TooltipVariantProps = TooltipProps | KeyboardKeyTooltipProps;
+
 /*
  *Tooltip's current structure does not allow for customization of its arrow.
  *TODO: refactor Tooltip so that the styling of its arrow can be customized
  *using Customization Provider.
  */
 
-const Tooltip = React.forwardRef<HTMLDivElement, TooltipProps>(
-  ({ baseId, children, element = "TOOLTIP", state, text, ...props }, ref) => {
+const Tooltip = React.forwardRef<HTMLDivElement, TooltipVariantProps>(
+  ({ baseId, children, element = "TOOLTIP", state, text, actionHeader, keyCombinationsActions, ...props }, ref) => {
     const tooltip = state || useTooltipPrimitiveState({ baseId: `paste-tooltip-${useUID()}`, ...props });
+
     return (
       <>
         {React.Children.only(
           <TooltipPrimitiveReference {...tooltip} ref={ref} {...children.props}>
             {(referenceProps) => React.cloneElement(children, referenceProps)}
-          </TooltipPrimitiveReference>,
+          </TooltipPrimitiveReference>
         )}
         <TooltipPrimitive element={element} {...tooltip} {...props} as={StyledTooltip}>
           {/* import Paste Theme Based Styles due to portal positioning. */}
           <StyledBase>
             <TooltipArrow {...tooltip} />
-            <Text
-              element={`${element}_TEXT`}
-              as="span"
-              color="colorTextInverse"
-              fontSize="fontSize20"
-              lineHeight="lineHeight10"
-            >
-              {text}
-            </Text>
+            {text && !keyCombinationsActions && (
+              <Text
+                element={`${element}_TEXT`}
+                as="span"
+                color="colorTextInverse"
+                fontSize="fontSize20"
+                lineHeight="lineHeight10"
+              >
+                {text}
+              </Text>
+            )}
+            {keyCombinationsActions && (
+              <Stack orientation="vertical" spacing="space30">
+                {actionHeader && (
+                  <Text element={`${element}_HEADER`} fontWeight="fontWeightSemibold" as="p" color="colorTextInverse">
+                    {actionHeader}
+                  </Text>
+                )}
+                {keyCombinationsActions.map((action, idx) => (
+                  <Box display="flex" key={`action-${idx}`} justifyContent="space-between">
+                    {action.name && (
+                      <Text
+                        element={`${element}_ACTION_TEXT`}
+                        as="span"
+                        color="colorTextInverse"
+                        fontSize="fontSize20"
+                        lineHeight="lineHeight10"
+                        marginRight="space70"
+                      >
+                        {action.name}
+                      </Text>
+                    )}
+                    <KeyboardKeyGroup
+                      variant="inverse"
+                      element={`${element}_ACTION_KEY_GROUP`}
+                      disabled={action.disabled}
+                    >
+                      {action.eventKeyCombination.map((key, i) => (
+                        <KeyboardKey key={`key-${idx}-${i}`} element={`${element}_ACTION_KEY`}>
+                          {key}
+                        </KeyboardKey>
+                      ))}
+                    </KeyboardKeyGroup>
+                  </Box>
+                ))}
+              </Stack>
+            )}
           </StyledBase>
         </TooltipPrimitive>
       </>
     );
-  },
+  }
 );
 
 Tooltip.displayName = "Tooltip";

packages/paste-core/components/tooltip/src/index.tsx

@@ -3,6 +3,8 @@ import type { TooltipStateReturn } from "./Tooltip";
 export { Tooltip, useTooltipState } from "./Tooltip";
 export type {
   TooltipProps,
+  TooltipVariantProps,
+  KeyboardKeyTooltipProps,
   TooltipStateReturn,
   UseTooltipInitialStateProps,
 } from "./Tooltip";

packages/paste-core/components/tooltip/stories/keyboard-key.stories.tsx

@@ -0,0 +1,137 @@
+import type { StoryFn } from "@storybook/react";
+import { Anchor } from "@twilio-paste/anchor";
+import { Box } from "@twilio-paste/box";
+import { Button } from "@twilio-paste/button";
+import { CustomizationProvider } from "@twilio-paste/customization";
+import { InformationIcon } from "@twilio-paste/icons/esm/InformationIcon";
+import { Stack } from "@twilio-paste/stack";
+import { Text } from "@twilio-paste/text";
+import { Theme, useTheme } from "@twilio-paste/theme";
+import * as React from "react";
+
+import { Tooltip, useTooltipState } from "../src";
+
+// eslint-disable-next-line import/no-default-export
+export default {
+  title: "Components/Tooltip/KeyboardKey",
+  excludeStories: ["StateHookExample"],
+  component: Tooltip,
+  parameters: {
+    chromatic: { delay: 3000, diffThreshold: 0.2 },
+  },
+};
+
+export const Default = (): React.ReactNode => {
+  return (
+    <Box as="div" minHeight="400px">
+      <Tooltip
+        visible
+        actionHeader="Search shortcuts"
+        keyCombinationsActions={[
+          { name: "Mac", eventKeyCombination: ["Command", "K"] },
+          { name: "Windows", eventKeyCombination: ["Control", "K"] },
+        ]}
+      >
+        <Button aria-keyshortcuts="command+k" variant="primary">
+          Click to search
+        </Button>
+      </Tooltip>
+    </Box>
+  );
+};
+
+export const CustomizedTooltip: StoryFn = (_args, { parameters: { isTestEnvironment } }) => {
+  const currentTheme = useTheme();
+  return (
+    <CustomizationProvider
+      disableAnimations={isTestEnvironment}
+      theme={currentTheme}
+      elements={{
+        TOOLTIP: {
+          backgroundColor: "colorBackgroundErrorWeakest",
+          borderColor: "colorBorderDestructive",
+          textAlign: "center",
+        },
+        TOOLTIP_ACTION_TEXT: {
+          color: "colorTextErrorStrong",
+        },
+        TOOLTIP_HEADER: {
+          color: "colorTextLinkDestructive",
+          fontWeight: "fontWeightBold",
+        },
+        TOOLTIP_ACTION_KEY_GROUP: {
+          backgroundColor: "colorBackgroundStrong",
+          padding: "space30",
+        },
+        TOOLTIP_ACTION_KEY: {
+          backgroundColor: "colorBackgroundPrimary",
+          color: "colorTextInverse",
+        },
+        CUSTOM_TOOLTIP: {
+          backgroundColor: "colorBackgroundSuccessWeakest",
+          borderColor: "colorBorderSuccess",
+          textAlign: "left",
+        },
+        CUSTOM_TOOLTIP_ACTION_TEXT: {
+          color: "colorTextSuccess",
+        },
+        CUSTOM_TOOLTIP_HEADER: {
+          color: "colorTextLinkStrongest",
+          fontWeight: "fontWeightLight",
+        },
+        CUSTOM_TOOLTIP_ACTION_KEY_GROUP: {
+          backgroundColor: "colorBackgroundInverse",
+          padding: "space30",
+        },
+        CUSTOM_TOOLTIP_ACTION_KEY: {
+          backgroundColor: "colorBackgroundBusy",
+          color: "colorTextInverse",
+          fontFamily: "fontFamilyCode",
+        },
+      }}
+    >
+      <Box as="div" display="flex" columnGap="space80">
+        <Box minWidth="200px">
+          <Tooltip
+            visible
+            actionHeader="Search shortcuts"
+            keyCombinationsActions={[
+              { name: "Mac", eventKeyCombination: ["Command", "K"] },
+              { name: "Windows", eventKeyCombination: ["Control", "K"] },
+            ]}
+          >
+            <Button aria-keyshortcuts="command+k" variant="primary">
+              Click to search
+            </Button>
+          </Tooltip>
+        </Box>
+        <Box minWidth="600px">
+          <Tooltip
+            element="CUSTOM_TOOLTIP"
+            visible
+            actionHeader="Search shortcuts"
+            keyCombinationsActions={[
+              { name: "Mac", eventKeyCombination: ["Command", "K"] },
+              { name: "Windows", eventKeyCombination: ["Control", "K"] },
+            ]}
+          >
+            <Button aria-keyshortcuts="command+k" variant="primary">
+              Click to search
+            </Button>
+          </Tooltip>
+        </Box>
+      </Box>
+    </CustomizationProvider>
+  );
+};
+
+CustomizedTooltip.storyName = "Customized Tooltip";
+CustomizedTooltip.parameters = {
+  parameters: {
+    chromatic: { disableSnapshot: true },
+  },
+  a11y: {
+    // no need to a11y check customization
+    disable: true,
+  },
+};