refactor: rewrite IconSwitch in typescript (#19141)

Author: adamalston

packages/react/src/components/ContentSwitcher/ContentSwitcher.tsx

@@ -27,13 +27,7 @@ import { getNextIndex, matches, keys } from '../../internal/keyboard';
 import { PrefixContext } from '../../internal/usePrefix';
 import { noopFn } from '../../internal/noopFn';
 import { IconSwitch } from '../Switch';
-
-export interface SwitchEventHandlersParams {
-  index?: number;
-  name?: string | number;
-  text?: string;
-  key?: string | number;
-}
+import type { SwitchEventHandlersParams } from '../Switch/Switch';
 
 export interface ContentSwitcherProps
   extends Omit<HTMLAttributes<HTMLElement>, 'onChange'> {

packages/react/src/components/IconButton/IconButton.stories.js

@@ -57,6 +57,10 @@ Default.args = {
 
 Default.argTypes = {
   align: {
+    // TODO:
+    // 1. Should the deprecated options be deleted?
+    // 2. The list doesn't include all of the options available in the
+    //    component. Is it supposed to?
     options: [
       'top',
       'top-left',

packages/react/src/components/Switch/IconSwitch.js renamed to packages/react/src/components/Switch/IconSwitch.tsx

@@ -6,14 +6,64 @@
  */
 
 import PropTypes from 'prop-types';
-import React, { useState } from 'react';
+import React, {
+  forwardRef,
+  useState,
+  type KeyboardEvent,
+  type MouseEvent,
+  type ReactNode,
+} from 'react';
 import classNames from 'classnames';
-import { IconButton } from '../IconButton';
+import { IconButton, type IconButtonProps } from '../IconButton';
 import { usePrefix } from '../../internal/usePrefix';
+import { noopFn } from '../../internal/noopFn';
+import type { SwitchEventHandlersParams } from './Switch';
 
-const noopFn = () => {};
+interface IconSwitchProps
+  extends Omit<IconButtonProps, 'onClick' | 'onKeyDown' | 'label' | 'name'> {
+  /**
+   * The index of the `IconSwitch`.
+   *
+   * Reserved for usage in `ContentSwitcher`.
+   */
+  index?: number;
+
+  /**
+   * The name of the `IconSwitch`.
+   */
+  name?: string | number;
+
+  /**
+   * A handler that is invoked when a user clicks on the control.
+   *
+   * Reserved for usage in `ContentSwitcher`.
+   */
+  onClick?: (params: SwitchEventHandlersParams) => void;
+
+  /**
+   * A handler that is invoked on the key down event for the control.
+   *
+   * Reserved for usage in `ContentSwitcher`.
+   */
+  onKeyDown?: (params: SwitchEventHandlersParams) => void;
 
-const IconSwitch = React.forwardRef(function Switch(props, tabRef) {
+  /**
+   * Whether the `IconSwitch` is selected.
+   *
+   * Reserved for usage in `ContentSwitcher`.
+   */
+  selected?: boolean;
+
+  // TODO: Why isn't this prop named `label` to match the `IconButton` prop?
+  /**
+   * `Tooltip` text.
+   */
+  text?: string;
+}
+
+const frFn = forwardRef<HTMLButtonElement, IconSwitchProps>;
+
+const IconSwitch = frFn((props, ref) => {
   const {
     align,
     children,
@@ -33,12 +83,13 @@ const IconSwitch = React.forwardRef(function Switch(props, tabRef) {
   const prefix = usePrefix();
   const [isHovered, setIsHovered] = useState(false);
 
-  const handleClick = (e) => {
-    e.preventDefault();
+  const handleClick = (event: MouseEvent<HTMLButtonElement>) => {
+    event.preventDefault();
     onClick({ index, name, text });
   };
 
-  const handleKeyDown = (event) => {
+  const handleKeyDown = (event: KeyboardEvent<HTMLButtonElement>) => {
+    // TODO: `which` was deprecated years ago. When can its usage be deleted?
     const key = event.key || event.which;
 
     onKeyDown({ index, name, text, key });
@@ -64,22 +115,11 @@ const IconSwitch = React.forwardRef(function Switch(props, tabRef) {
     }
   );
 
-  const commonProps = {
-    onClick: handleClick,
-    onKeyDown: handleKeyDown,
-    className: classes,
-    disabled,
-    align,
-    enterDelayMs,
-    leaveDelayMs,
-    size,
-  };
-
   return (
     <IconButton
       label={text}
       type="button"
-      ref={tabRef}
+      ref={ref}
       role="tab"
       tabIndex={selected || isHovered ? 0 : -1}
       onMouseEnter={handleMouseEnter}
@@ -90,7 +130,14 @@ const IconSwitch = React.forwardRef(function Switch(props, tabRef) {
       aria-label={text}
       wrapperClasses={iconButtonClasses}
       {...other}
-      {...commonProps}>
+      align={align}
+      className={classes}
+      disabled={disabled}
+      enterDelayMs={enterDelayMs}
+      leaveDelayMs={leaveDelayMs}
+      onClick={handleClick}
+      onKeyDown={handleKeyDown}
+      size={size}>
       {children}
     </IconButton>
   );
@@ -114,17 +161,17 @@ IconSwitch.propTypes = {
   ]),
 
   /**
-   * Provide child elements to be rendered inside of the Switch
+   * Children to be rendered inside of the `IconSwitch`.
    */
   children: PropTypes.node,
 
   /**
-   * Specify an optional className to be added to your Switch
+   * Specify an optional className to be added to your `IconSwitch`.
    */
   className: PropTypes.string,
 
   /**
-   * Specify whether or not the Switch should be disabled
+   * Whether the `IconSwitch` should be disabled.
    */
   disabled: PropTypes.bool,
 
@@ -134,8 +181,9 @@ IconSwitch.propTypes = {
   enterDelayMs: PropTypes.number,
 
   /**
-   * The index of your Switch in your ContentSwitcher that is used for event handlers.
-   * Reserved for usage in ContentSwitcher
+   * The index of the `IconSwitch`.
+   *
+   * Reserved for usage in `ContentSwitcher`.
    */
   index: PropTypes.number,
 
@@ -145,34 +193,39 @@ IconSwitch.propTypes = {
   leaveDelayMs: PropTypes.number,
 
   /**
-   * Provide the name of your Switch that is used for event handlers
+   * The name of the `IconSwitch`.
    */
   name: PropTypes.oneOfType([PropTypes.string, PropTypes.number]),
 
   /**
    * A handler that is invoked when a user clicks on the control.
-   * Reserved for usage in ContentSwitcher
+   *
+   * Reserved for usage in `ContentSwitcher`.
    */
   onClick: PropTypes.func,
 
   /**
    * A handler that is invoked on the key down event for the control.
-   * Reserved for usage in ContentSwitcher
+   *
+   * Reserved for usage in `ContentSwitcher`.
    */
   onKeyDown: PropTypes.func,
 
   /**
-   * Whether your Switch is selected. Reserved for usage in ContentSwitcher
+   * Whether the `IconSwitch` is selected.
+   *
+   * Reserved for usage in `ContentSwitcher`.
    */
   selected: PropTypes.bool,
 
+  // TODO: Icon only variant of what? Isn't the `IconSwitch` always icon only?
   /**
    * Passed in from `ContentSwitcher` to render icon-only variant
    */
   size: PropTypes.oneOf(['sm', 'md', 'lg']),
 
   /**
-   * Provide the visible text displayed by the Tooltip
+   * `Tooltip` text.
    */
   text: PropTypes.string,
 };

packages/react/src/components/Switch/Switch.tsx

@@ -101,6 +101,7 @@ const Switch = React.forwardRef<HTMLButtonElement, SwitchProps>(function Switch(
   };
 
   const handleKeyDown = (event: KeyboardEvent<HTMLButtonElement>) => {
+    // TODO: `which` was deprecated years ago. When can its usage be deleted?
     const key = event.key || event.which;
 
     onKeyDown?.({ index, name, text, key });

packages/react/src/components/Toggletip/Toggletip.stories.js

@@ -114,6 +114,10 @@ export const Default = (args) => {
 
 Default.argTypes = {
   align: {
+    // TODO:
+    // 1. Should the deprecated options be deleted?
+    // 2. The list doesn't include all of the options available in the
+    //    component. Is it supposed to?
     options: [
       'top',
       'top-left',

packages/react/src/components/Tooltip/DefinitionTooltip.stories.js

@@ -68,6 +68,10 @@ Default.args = {
 
 Default.argTypes = {
   align: {
+    // TODO:
+    // 1. Should the deprecated options be deleted?
+    // 2. The list doesn't include all of the options available in the
+    //    component. Is it supposed to?
     options: [
       'top',
       'top-left',

packages/react/src/components/Tooltip/Tooltip.stories.js

@@ -66,6 +66,10 @@ export const Default = (args) => {
 
 Default.argTypes = {
   align: {
+    // TODO:
+    // 1. Should the deprecated options be deleted?
+    // 2. The list doesn't include all of the options available in the
+    //    component. Is it supposed to?
     options: [
       'top',
       'top-left',

packages/react/src/components/UIShell/HeaderPanel.tsx

@@ -20,6 +20,7 @@ import { keys, match } from '../../internal/keyboard';
 import { useWindowEvent } from '../../internal/useEvent';
 import { useMergedRefs } from '../../internal/useMergedRefs';
 import Switcher from './Switcher';
+import { noopFn } from '../../internal/noopFn';
 
 export interface HeaderPanelProps {
   /**
@@ -54,7 +55,6 @@ export interface HeaderPanelProps {
   onHeaderPanelFocus?: () => void;
 }
 
-const noopFn = () => {};
 const HeaderPanel: React.FC<HeaderPanelProps> = React.forwardRef(
   function HeaderPanel(
     {