@react-fabric/core 1.0.0-beta.9 → 1.0.1

package/src/components/button/Button.tsx

@@ -1,10 +1,8 @@
 /*
  * React Fabric
  * @version: 1.0.0
- *
- *
  * The MIT License (MIT)
- * Copyright (c) 2024 Adarsh Pastakia
+ * Copyright (c) 2026 Adarsh Pastakia
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy of this software
  * and associated documentation files (the "Software"), to deal in the Software without restriction,
@@ -21,306 +19,293 @@
  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-import { isNil, isString, mergeRefs } from "@react-fabric/utilities";
-import classNames from "classnames";
-import {
-  Fragment,
-  isValidElement,
-  type MouseEventHandler,
-  useCallback,
-  useEffect,
-  useMemo,
-  useRef,
-  useState,
-  type WheelEventHandler,
-} from "react";
-import { useEffectDebugger } from "../../hooks/useEffectDebugger";
-import { HotKey } from "../../hotkeys/HotKey";
-import { HotKeyLabel } from "../../hotkeys/HotKeyLabel";
-import { Tooltip } from "../../overlays/tooltip/Tooltip";
-import {
-  type AriaProps,
-  type BadgeType,
-  type CallbackReturn,
-  type ColorType,
-  type CssProp,
-  type IconProps,
-  type PolymorphicProps,
-  type RefProp,
-  type SizeType,
-  type TestProps,
-  type TooltipType,
-} from "../../types";
-import { AnimationIndicator } from "../animations/Animations";
-import { Badge, getBadgeProps } from "../badge/Badge";
+import { cn, EMPTY_ARRAY } from "@react-fabric/utilities";
+import type { Hotkey } from "@tanstack/react-hotkeys";
+import { useHotkeySequence } from "@tanstack/react-hotkeys";
+import { useEffect, useReducer } from "react";
+import type { ChildProp, CssPropWithMap, CSSSizeType, HtmlEvents, PolymorphicProps, RefProp, SizeType, TestProps } from "../../types";
+import { Kbd } from "../../typography/Kbd";
+import { getIconProps } from "../../utils";
+import { AnimationIndicator } from "../animations/Indicator";
+import { StyleEffect } from "../effect/StyleEffect";
+import type { IconProps } from "../icon/Icon";
 import { Icon } from "../icon/Icon";
-import classes from "./Button.module.css";
 
-export interface BaseProps
-  extends CssProp,
-    AriaProps,
-    IconProps,
-    RefProp,
-    TestProps {
+export interface SharedButtonProps extends HtmlEvents {
   /**
-   * primary icon alignment
+   * Visual style variant of the button. Defaults to `"default"`.
    */
-  iconAlign?: "start" | "end";
+  variant?: "default" | "soft" | "outlined" | "dashed" | "solid" | "link";
+
   /**
-   * alternate icon align end (caret, arrow)
+   * Color scheme for the button. Defaults to `"default"`.
    */
-  altIcon?: string;
+  color?: "default" | "muted" | "primary" | "secondary" | "info" | "danger" | "success" | "warning";
+
   /**
-   * button size
+   * When true, applies fully rounded (pill) corners to the button.
    */
-  size?: SizeType;
+  rounded?: boolean;
+
   /**
-   * button color
+   * Button size. Accepts `"xs"`, `"sm"`, `"md"`, `"lg"`, or `"xl"`.
    */
-  color?: ColorType;
+  size?: SizeType;
+}
+
+interface BaseButtonProps
+  extends CssPropWithMap<{ root: string; button: string; label: string; icon: string }>, RefProp<HTMLButtonElement>, TestProps, SharedButtonProps {
+  "aria-label"?: string;
+
   /**
-   * button type
+   * Keyboard shortcut combo that triggers the button's `onClick` handler.
    */
-  type?: "button" | "reset" | "submit";
+  hotKey?: Hotkey | Hotkey[];
   /**
-   * button styling
+   * When true, hides the visual hotkey label displayed inside the button.
    */
-  variant?: "outline" | "solid" | "link";
+  hideHotKeyLabel?: boolean;
+
   /**
-   * active state with click disabled
+   * Icon path or props rendered inside the button.
    */
-  active?: boolean;
+  icon?: IconProps;
   /**
-   * loading state with animation and click disabled
+   * Alternative icon rendered for dropdown carets or state indicators.
    */
-  loading?: boolean;
+  altIcon?: IconProps;
+
   /**
-   * full rounded edges
+   * When true, marks the button as in an active/selected state.
    */
-  rounded?: boolean;
+  active?: boolean;
   /**
-   * spin icon on hover
+   * When true, shows a loading spinner and disables clicks to prevent duplicate submissions.
    */
-  spinOnHover?: boolean;
+  loading?: boolean;
   /**
-   * disabled state
+   * When true, disables the button and prevents user interaction.
    */
   disabled?: boolean;
+
   /**
-   * stretch to full width
+   * When true, allows the button to be clicked even when `active` is true.
    */
-  fullWidth?: boolean;
+  activeClickable?: boolean;
+
+  type?: "button" | "submit" | "reset";
+
   /**
-   * action completed message works best with `onClick` Promise return.
-   * To hide completed message onClick/Promise return should be false
+   * Explicit width of the button (CSS size value).
    */
-  actionMessage?: string;
+  width?: CSSSizeType;
   /**
-   * manually force show action message
+   * When true, manually shows the action-completed checkmark overlay.
    */
   showActionDone?: boolean;
   /**
-   * show action message `onClick` or manually by setting `showActionDone` true
+   * Controls when the action-completed checkmark appears: `"click"` shows it after onClick,
+   * `"manual"` requires setting `showActionDone` to true.
    */
   showActionDoneEvent?: "click" | "manual";
-  /**
-   * click handler, return Promise to autoset loading state
-   */
-  onClick?: (e?: React.MouseEvent) => CallbackReturn;
-  /**
-   * badges
-   */
-  badge?: string | number | BadgeType;
-  /**
-   * keyboard shortcut
-   */
-  hotKey?: string;
-
-  stopPropagation?: boolean;
-
-  onMouseOut?: MouseEventHandler;
-  onMouseOver?: MouseEventHandler;
-  onMouseMove?: MouseEventHandler;
-  onMouseEnter?: MouseEventHandler;
-  onMouseLeave?: MouseEventHandler;
-
-  onWheel?: WheelEventHandler;
 }
 
-export type ButtonProps =
-  | { children: string | React.ReactElement; "aria-label"?: string }
-  | { children?: never; "aria-label": string };
+type ButtonTypeProps = { children: ChildProp["children"] } | { children?: never; "aria-label": string };
+
+export type ButtonProps<Tag extends React.ElementType = "button"> = BaseButtonProps & ButtonTypeProps & PolymorphicProps<Tag>;
 
 /**
- * Clickable action button
+ * A versatile button component that supports multiple variants, colors, sizes, and states.
+ * It can display icons, handle loading/action states, show keyboard shortcuts, and be
+ * polymorphic to render as different HTML elements or custom components.
+ *
+ * @example
+ * ```tsx
+ * // Basic button
+ * <Button variant="solid" color="primary" onClick={handleClick}>
+ *   Click me
+ * </Button>
+ *
+ * // Icon button with loading state
+ * <Button icon="icon-[mdi--floppy]" loading={saving}>
+ *   Save
+ * </Button>
+ *
+ * // Polymorphic: renders as a link
+ * <Button as="a" href="/dashboard" variant="soft">
+ *   Dashboard
+ * </Button>
+ *
+ * // Button with keyboard shortcut
+ * <Button hotKey="Ctrl+S" variant="dashed">
+ *   Save (Ctrl+S)
+ * </Button>
+ * ```
  */
-export const Button = <Tag extends React.ElementType = "button">({
+export function Button<Tag extends React.ElementType = "button">({
+  active,
+  altIcon,
   as,
-  ref,
   children,
   className,
-  active,
-  color = "primary",
-  icon,
-  iconBg,
-  iconColor,
-  iconAlign = "start",
-  altIcon,
-  rtlFlip,
-  rounded,
-  size,
+  classNames,
+  color = "default",
   disabled,
+  icon,
   loading,
-  variant,
-  badge,
-  fullWidth,
-  spinOnHover,
+  onBlur,
   onClick,
-  actionMessage,
-  stopPropagation,
+  onFocus,
+  onMouseDown,
+  onMouseEnter,
+  onMouseLeave,
+  onMouseMove,
+  onMouseOver,
+  onMouseUp,
+  activeClickable,
+  showActionDone,
+  showActionDoneEvent,
   type = "button",
+  ref,
+  rounded,
+  size,
+  variant = "default",
+  width,
   hotKey,
-  showActionDone,
-  showActionDoneEvent = "click",
-  tabIndex = 0,
-  // @ts-expect-error ignore
-  "data-ref": dataRef,
-  ...aria
-}: BaseProps & ButtonProps & PolymorphicProps<Tag>) => {
-  const refEl = useRef<AnyObject>(null);
-  const [busy, setBusy] = useState(false);
-  const [actionDone, setActionDone] = useState(false);
-
-  const clickHandler = useCallback(
-    (e: React.MouseEvent) => {
-      setBusy(true);
-      stopPropagation && e.stopPropagation();
-      const ret = onClick?.(e);
-      void Promise.resolve(ret).then((b) => {
-        setBusy(false);
-        if (b !== false && actionMessage && showActionDoneEvent === "click") {
-          setActionDone(true);
-        }
-      });
+  hideHotKeyLabel,
+  ...props
+}: ButtonProps<Tag>) {
+  // Action state: tracks whether an action is running and whether to show the done overlay
+  const [state, dispatch] = useReducer(
+    (state, action: { type: string }) => {
+      // Start action: show spinner, hide done overlay
+      if (action.type === "actionStart") {
+        return { isActionRunning: true, showActionDone: false };
+      }
+      // Action finished: hide spinner
+      if (action.type === "actionFinished") {
+        return { ...state, isActionRunning: false };
+      }
+      // Action done: show checkmark overlay
+      if (action.type === "actionDone") {
+        return { isActionRunning: false, showActionDone: true };
+      }
+      // Reset: hide everything
+      return { isActionRunning: false, showActionDone: false };
+    },
+    {
+      isActionRunning: false,
+      showActionDone: false,
     },
-    [onClick, disabled, actionMessage, showActionDoneEvent, stopPropagation],
   );
+  // Handle button click: dispatch action start, run onClick, then dispatch finished
+  const handleAction = async (e?: React.MouseEvent) => {
+    dispatch({ type: "actionStart" });
+    try {
+      await Promise.resolve(onClick?.(e));
+      if (showActionDoneEvent === "click") {
+        dispatch({ type: "actionDone" });
+        setTimeout(() => dispatch({ type: "actionReset" }), 2000);
+      }
+    } finally {
+      dispatch({ type: "actionFinished" });
+    }
+  };
 
-  /** ***************** reset done state on timeout *******************/
-  useEffect(() => {
-    actionMessage && showActionDone && setActionDone(true);
-  }, [showActionDone, actionMessage]);
-  useEffectDebugger(
+  useHotkeySequence(
+    hotKey ? [hotKey].flat() : EMPTY_ARRAY,
     () => {
-      if (actionDone) {
-        const timer = setTimeout(() => setActionDone(false), 2000);
-        return () => clearTimeout(timer);
-      }
+      void handleAction();
+    },
+    {
+      enabled: !disabled,
     },
-    [actionDone],
-    "ActionButton done handler",
   );
 
-  const TooltipWrapper = useMemo(
-    () => (actionMessage ? Tooltip : Fragment),
-    [actionMessage, actionDone],
-  );
-  const tooltipProps = useMemo(() => {
-    if (actionDone && actionMessage) {
-      return {
-        content: actionMessage,
-        placement: "top",
-        color,
-        open: true,
-      } as TooltipType;
+  // Manual mode: show/hide the done overlay based on showActionDone prop
+  useEffect(() => {
+    if (showActionDoneEvent === "manual") {
+      if (showActionDone) dispatch({ type: "actionDone" });
+      return () => {
+        dispatch({ type: "actionFinished" });
+      };
     }
-  }, [actionDone, actionMessage, color]);
-
-  const badgeProps = useMemo(() => {
-    return getBadgeProps(badge);
-  }, [badge]);
+  }, [showActionDone, showActionDoneEvent]);
 
   const E = as ?? "button";
   return (
     <div
-      className={classNames(
-        classes.buttonWrapper,
-        className,
-        "relative align-text-top select-none focus-within:z-1",
-        fullWidth ? "block w-full" : "inline-block",
-      )}
-      data-ref={dataRef ?? "button"}
-      data-size={size}
-      data-loading={busy || loading}
+      className={cn("fabric-buttonWrapper", "inline-flex relative is-disabled:cursor-not-allowed is-loading:cursor-wait", className, classNames?.root)}
+      data-loading={loading || state.isActionRunning}
       data-disabled={disabled}
+      data-rounded={rounded}
+      data-variant={variant}
+      data-active={active}
+      data-color={color}
+      data-size={size}
+      style={{
+        width: width,
+      }}
     >
-      {hotKey && (
-        <HotKey
-          keyCombo={hotKey}
-          handler={() => !disabled && refEl.current?.click()}
-        />
-      )}
-      <TooltipWrapper {...tooltipProps}>
-        <E
-          ref={mergeRefs(ref, refEl)}
-          role="button"
-          className={classNames(
-            classes.button,
-            "pointer-events-auto cursor-pointer select-none flex flex-nowrap w-full h-full items-center border-0 -outline-offset-1 justify-center max-w-72 p-0 font-sans font-medium appearance-none",
-            `focus-visible:ring-2 focus-visible:ring-offset-2 buttonInner`,
-            fullWidth && "max-w-full w-full",
-            rounded && "rounded-full",
-            spinOnHover && classes.spinOnHover,
-          )}
-          type={type}
-          disabled={disabled}
-          tabIndex={tabIndex}
-          data-inner-clickable
-          onClick={clickHandler}
-          data-color={color}
-          data-active={active}
-          data-variant={variant}
-          {...aria}
-        >
-          {icon && (
-            <Icon
-              className={classes.buttonIcon}
-              icon={icon}
-              bg={iconBg}
-              color={iconColor}
-              rtlFlip={rtlFlip}
-              data-align={iconAlign}
-            />
-          )}
-          {isValidElement(children) && (
-            <div className={classes.buttonChild}>{children}</div>
-          )}
-          {isString(children) && (
-            <label
-              className={classNames(classes.buttonLabel, "truncate")}
-              data-colored-icon={!!iconBg}
-            >
-              {children}
-            </label>
-          )}
-          {!isNil(badge) && <Badge {...badgeProps} />}
-          {hotKey && <HotKeyLabel keyCombo={hotKey} />}
-          {altIcon && (
-            <Icon className={classes.altIcon} icon={altIcon} rtlFlip />
-          )}
-        </E>
-      </TooltipWrapper>
-      {actionDone && (
+      <E
+        ref={ref}
+        {...props}
+        type={type}
+        className={cn(
+          "fabric-button",
+          classNames?.button,
+          "relative w-full appearance-none outline cursor-pointer overflow-hidden flex items-center justify-center has-[.fabric-buttonLabel]:px-[0.5em]",
+          "rounded is-rounded:rounded-full",
+          "is-loading:pointer-events-none is-loading:after:animate-progress is-disabled:pointer-events-none",
+          "not-is-active:is-disabled:opacity-50 not-is-active:is-disabled:after:bg-tint-500/10",
+          !activeClickable && "is-active:pointer-events-none",
+        )}
+        data-clickable={true}
+        data-ref="button"
+        data-testid={props["data-testid"]}
+        data-test-value={props["data-test-value"]}
+        role="button"
+        disabled={disabled}
+        aria-label={props["aria-label"]}
+        aria-disabled={disabled}
+        onFocus={onFocus}
+        onBlur={onBlur}
+        // eslint-disable-next-line @typescript-eslint/no-misused-promises
+        onClick={handleAction}
+        onMouseDown={onMouseDown}
+        onMouseUp={onMouseUp}
+        onMouseOver={onMouseOver}
+        onMouseMove={onMouseMove}
+        onMouseEnter={onMouseEnter}
+        onMouseLeave={onMouseLeave}
+      >
+        {variant !== "link" && <StyleEffect />}
+        {icon && (
+          <Icon
+            className={cn(
+              "fabric-buttonIcon",
+              classNames?.icon,
+              "m-[0.375em] has-[~_.fabric-buttonLabel]:mx-0 inline-block size-fit flex-content pointer-events-none",
+            )}
+            {...getIconProps(icon)}
+          />
+        )}
+        {children && (
+          <div className={cn("fabric-buttonLabel", classNames?.label, "m-[0.25em] truncate flex-[0_1_auto] leading-tight pointer-events-none")}>{children}</div>
+        )}
+        {!hideHotKeyLabel && hotKey && <Kbd keys={hotKey} />}
+        {altIcon && (
+          <Icon className={cn("fabric-buttonAltIcon", "my-[0.25em] size-fit inline-block flex-content pointer-events-none")} {...getIconProps(altIcon)} />
+        )}
+      </E>
+      {state.showActionDone && (
         <div
-          className={classNames(
-            "absolute inset-0 overflow-hidden flex justify-center items-center",
-            `bg-${color}-300`,
-            rounded ? "rounded-full" : "rounded",
-          )}
+          data-testid="doneOverlay"
+          className="fabric-buttonDoneOverlay absolute inset-0 flex items-center justify-center z-1 border rounded is-rounded:rounded-full"
         >
-          <AnimationIndicator type="check" color={color} />
+          <AnimationIndicator type="check" />
         </div>
       )}
     </div>
   );
-};
+}