@react-fabric/core 1.0.0-beta.5 → 1.0.0-beta.52

package/src/components/button/Button.tsx

@@ -26,12 +26,12 @@ import classNames from "classnames";
 import {
   Fragment,
   isValidElement,
-  type MouseEventHandler,
   useCallback,
   useEffect,
   useMemo,
   useRef,
   useState,
+  type MouseEventHandler,
   type WheelEventHandler,
 } from "react";
 import { useEffectDebugger } from "../../hooks/useEffectDebugger";
@@ -39,10 +39,10 @@ import { HotKey } from "../../hotkeys/HotKey";
 import { HotKeyLabel } from "../../hotkeys/HotKeyLabel";
 import { Tooltip } from "../../overlays/tooltip/Tooltip";
 import {
+  type ColorState,
   type AriaProps,
   type BadgeType,
   type CallbackReturn,
-  type ColorType,
   type CssProp,
   type IconProps,
   type PolymorphicProps,
@@ -51,10 +51,10 @@ import {
   type TestProps,
   type TooltipType,
 } from "../../types";
+import { getColor } from "../../utils";
 import { AnimationIndicator } from "../animations/Animations";
 import { Badge, getBadgeProps } from "../badge/Badge";
 import { Icon } from "../icon/Icon";
-import classes from "./Button.module.css";
 
 export interface BaseProps
   extends CssProp,
@@ -77,7 +77,7 @@ export interface BaseProps
   /**
    * button color
    */
-  color?: ColorType;
+  color?: ColorState;
   /**
    * button type
    */
@@ -85,7 +85,7 @@ export interface BaseProps
   /**
    * button styling
    */
-  variant?: "outline" | "solid" | "link";
+  variant?: "outline" | "soft" | "solid" | "link";
   /**
    * active state with click disabled
    */
@@ -147,12 +147,37 @@ export interface BaseProps
   onWheel?: WheelEventHandler;
 }
 
-export type ButtonProps =
+type ButtonTypeProps =
   | { children: string | React.ReactElement; "aria-label"?: string }
   | { children?: never; "aria-label": string };
 
+export type ButtonProps<Tag extends React.ElementType = "button"> = BaseProps &
+  ButtonTypeProps &
+  PolymorphicProps<Tag>;
+
 /**
- * Clickable action button
+ * A versatile button component that supports various styles, icons, and actions.
+ * It can be used as a primary action button, with options for loading states, action messages, and more.
+ * It supports polymorphic rendering, allowing it to be used as different HTML elements (e.g., button, a, div).
+ * It also includes features like after action tooltips, badges, and keyboard shortcuts.
+ *
+ * @param {ButtonProps} props - The properties for the Button component.
+ * @returns {JSX.Element} The rendered Button component.
+ *
+ * @example
+ * ```jsx
+ * <Button
+ *   color="primary"
+ *   size="md"
+ *   variant="solid"
+ *   icon="check"
+ *   onClick={() => console.log("Button clicked!")}
+ * >
+ *   Click Me
+ * </Button>
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/docs/core-components-button--docs} for more details.
  */
 export const Button = <Tag extends React.ElementType = "button">({
   as,
@@ -186,11 +211,12 @@ export const Button = <Tag extends React.ElementType = "button">({
   // @ts-expect-error ignore
   "data-ref": dataRef,
   ...aria
-}: BaseProps & ButtonProps & PolymorphicProps<Tag>) => {
+}: ButtonProps<Tag>) => {
   const refEl = useRef<AnyObject>(null);
   const [busy, setBusy] = useState(false);
   const [actionDone, setActionDone] = useState(false);
 
+  // Handle click events
   const clickHandler = useCallback(
     (e: React.MouseEvent) => {
       setBusy(true);
@@ -230,7 +256,7 @@ export const Button = <Tag extends React.ElementType = "button">({
       return {
         content: actionMessage,
         placement: "top",
-        color,
+        color: `${color}-100`,
         open: true,
       } as TooltipType;
     }
@@ -240,11 +266,15 @@ export const Button = <Tag extends React.ElementType = "button">({
     return getBadgeProps(badge);
   }, [badge]);
 
+  const hotKeyHandler = useRef(() => {
+    !disabled && refEl.current?.click();
+  });
+
   const E = as ?? "button";
   return (
     <div
       className={classNames(
-        classes.buttonWrapper,
+        "fabric-buttonWrapper",
         className,
         "relative align-text-top select-none focus-within:z-1",
         fullWidth ? "block w-full" : "inline-block",
@@ -254,23 +284,18 @@ export const Button = <Tag extends React.ElementType = "button">({
       data-loading={busy || loading}
       data-disabled={disabled}
     >
-      {hotKey && (
-        <HotKey
-          keyCombo={hotKey}
-          handler={() => !disabled && refEl.current?.click()}
-        />
-      )}
+      {hotKey && <HotKey keyCombo={hotKey} handler={hotKeyHandler.current} />}
       <TooltipWrapper {...tooltipProps}>
         <E
           ref={mergeRefs(ref, refEl)}
           role="button"
           className={classNames(
-            classes.button,
+            "fabric-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,
+            spinOnHover && "fabric-spinOnHover",
           )}
           type={type}
           disabled={disabled}
@@ -284,7 +309,7 @@ export const Button = <Tag extends React.ElementType = "button">({
         >
           {icon && (
             <Icon
-              className={classes.buttonIcon}
+              className={"fabric-buttonIcon"}
               icon={icon}
               bg={iconBg}
               color={iconColor}
@@ -293,11 +318,11 @@ export const Button = <Tag extends React.ElementType = "button">({
             />
           )}
           {isValidElement(children) && (
-            <div className={classes.buttonChild}>{children}</div>
+            <div className={"fabric-buttonChild"}>{children}</div>
           )}
           {isString(children) && (
             <label
-              className={classNames(classes.buttonLabel, "truncate")}
+              className={classNames("fabric-buttonLabel", "truncate")}
               data-colored-icon={!!iconBg}
             >
               {children}
@@ -306,7 +331,7 @@ export const Button = <Tag extends React.ElementType = "button">({
           {!isNil(badge) && <Badge {...badgeProps} />}
           {hotKey && <HotKeyLabel keyCombo={hotKey} />}
           {altIcon && (
-            <Icon className={classes.altIcon} icon={altIcon} rtlFlip />
+            <Icon className={"fabric-altIcon"} icon={altIcon} rtlFlip />
           )}
         </E>
       </TooltipWrapper>
@@ -314,9 +339,11 @@ export const Button = <Tag extends React.ElementType = "button">({
         <div
           className={classNames(
             "absolute inset-0 overflow-hidden flex justify-center items-center",
-            `bg-${color}-300`,
             rounded ? "rounded-full" : "rounded",
           )}
+          style={{
+            backgroundColor: getColor(`${color}-300`),
+          }}
         >
           <AnimationIndicator type="check" color={color} />
         </div>

package/src/components/button/ButtonGroup.tsx

@@ -22,18 +22,18 @@
  */
 
 import classNames from "classnames";
-import { Children, cloneElement } from "react";
+import { cloneElement } from "react";
 import {
   type AriaProps,
   type ChildrenProp,
-  type ColorType,
+  type ColorState,
   type CssProp,
   type RefProp,
   type SizeType,
   type TestProps,
 } from "../../types";
+import { cloneChildren } from "../../utils";
 import { type Button } from "./Button";
-import classes from "./Button.module.css";
 
 export interface ButtonGroupProps
   extends CssProp,
@@ -56,7 +56,7 @@ export interface ButtonGroupProps
   /**
    * button color
    */
-  color?: ColorType;
+  color?: ColorState;
   /**
    * full rounded edges
    */
@@ -71,6 +71,32 @@ export interface ButtonGroupProps
   fullWidth?: boolean;
 }
 
+/**
+ * A component that groups buttons together, allowing for consistent styling and behavior across multiple buttons.
+ * It supports vertical orientation, various button styles, and can handle properties like size, color, and disabled state.
+ * This component is useful for creating button groups that maintain a uniform appearance and functionality,
+ * such as toolbars, action groups, or navigation buttons.
+ *
+ * @param {ButtonGroupProps} props - The properties for the ButtonGroup component.
+ * @returns {JSX.Element} The rendered ButtonGroup component.
+ *
+ * @example
+ * ```jsx
+ * <ButtonGroup
+ *   variant="solid"
+ *   color="primary"
+ *   className="my-custom-class"
+ *   aria-label="Button Group"
+ *   vertical
+ * >
+ *   <Button>Button 1</Button>
+ *   <Button>Button 2</Button>
+ *   <Button>Button 3</Button>
+ * </ButtonGroup>
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/docs/core-components-buttongroup--docs} for more details.
+ */
 export const ButtonGroup = ({
   vertical,
   className,
@@ -87,16 +113,16 @@ export const ButtonGroup = ({
     <div
       data-ref="buttonGroup"
       className={classNames(
-        classes.buttonGroup,
+        "fabric-buttonGroup",
         className,
         fullWidth ? "flex" : "inline-flex",
         "flex-nowrap align-middle rounded",
-        vertical && classes.vertical,
+        vertical && "vertical",
         vertical && "flex-col items-stretch",
       )}
       {...aria}
     >
-      {Children.map(children, (child: AnyObject) =>
+      {cloneChildren(children, (child: AnyObject) =>
         cloneElement(child, {
           color,
           size,

package/src/components/button/ConfirmButton.tsx

@@ -22,18 +22,19 @@
  */
 
 import {
-  FloatingArrow,
-  FloatingFocusManager,
-  FloatingPortal,
   arrow,
   autoUpdate,
   flip,
+  FloatingArrow,
+  FloatingFocusManager,
+  FloatingPortal,
   offset,
   shift,
   useClick,
   useDismiss,
   useFloating,
   useInteractions,
+  type Placement,
 } from "@floating-ui/react";
 import { mergeRefs } from "@react-fabric/utilities";
 import classNames from "classnames";
@@ -66,6 +67,10 @@ interface ExtendedProps extends Omit<BaseProps, "onClick">, RefProp {
    * ok label
    */
   cancelLabel?: string;
+  /**
+   * dropdown placement
+   */
+  placement?: Placement;
   /**
    * click handler, return Promise to autoset loading state
    */
@@ -75,7 +80,28 @@ interface ExtendedProps extends Omit<BaseProps, "onClick">, RefProp {
 export type ConfirmButtonProps = ExtendedProps & ButtonProps;
 
 /**
- * Button with confirmation dropdown
+ * A button that shows a confirmation dialog when clicked, allowing the user to confirm or cancel an action.
+ * It supports custom messages, labels, and loading states.
+ * This component is useful for actions that require user confirmation, such as deleting items or submitting forms.
+ * It uses the Floating UI library to manage the positioning of the confirmation dialog, ensuring it appears correctly relative to the button.
+ * It also supports custom placement of the dialog, and can display an action message when the action is completed.
+ *
+ * @param {ConfirmButtonProps} props - The properties for the ConfirmButton component.
+ * @returns {JSX.Element} The rendered ConfirmButton component.
+ *
+ * @example
+ * ```jsx
+ * <ConfirmButton
+ *   message="Are you sure you want to delete this item?"
+ *   onClick={(confirmed) => {
+ *     if (confirmed) {
+ *       // Perform action
+ *     }
+ *   }}
+ * />
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/docs/core-components-confirmbutton--docs} for more details.
  */
 export const ConfirmButton = <Tag extends React.ElementType = "button">({
   ref,
@@ -85,6 +111,7 @@ export const ConfirmButton = <Tag extends React.ElementType = "button">({
   cancelLabel,
   onClick,
   loading,
+  placement = "bottom",
   actionMessage,
   showActionDone,
   showActionDoneEvent = "click",
@@ -127,7 +154,7 @@ export const ConfirmButton = <Tag extends React.ElementType = "button">({
       }
     },
     strategy: "fixed",
-    placement: "bottom",
+    placement,
     whileElementsMounted: autoUpdate,
     middleware: [
       shift({ padding: 8 }),
@@ -181,15 +208,21 @@ export const ConfirmButton = <Tag extends React.ElementType = "button">({
                 "select-none not-italic rounded-capped shadow-lg outline outline-muted bg-base",
               )}
               ref={refs.setFloating}
-              style={floatingStyles}
+              style={{
+                zIndex: "var(--z-popover)",
+                ...floatingStyles,
+              }}
               {...getFloatingProps()}
             >
               <div className="font-medium ">
-                <p className="py-2 px-4">{message}</p>
+                <p className="py-2 px-4" data-ref="confirmMessage">
+                  {message}
+                </p>
                 <div className="flex justify-end py-2 px-4 gap-2">
                   <Button
                     size="sm"
                     variant="link"
+                    data-ref="confirmCancel"
                     color={color}
                     onClick={() => [clickHandler(false), setIsOpen(false)]}
                   >
@@ -200,6 +233,7 @@ export const ConfirmButton = <Tag extends React.ElementType = "button">({
                     variant="solid"
                     color={color}
                     autoFocus
+                    data-ref="confirmOk"
                     onClick={() => [clickHandler(true), setIsOpen(false)]}
                   >
                     {okLabel ?? t("action.ok")}

package/src/components/button/ToggleButtonGroup.tsx

@@ -23,7 +23,7 @@
 
 import { EMPTY_ARRAY, isArray } from "@react-fabric/utilities";
 import classNames from "classnames";
-import { Children, cloneElement, useCallback, useMemo } from "react";
+import { cloneElement, useCallback } from "react";
 import { useControlledValue } from "../../hooks/useControlledValue";
 import {
   type AriaProps,
@@ -32,13 +32,10 @@ import {
   type CssProp,
   type SizeType,
 } from "../../types";
+import { cloneChildren } from "../../utils";
 import { type ButtonProps } from "./Button";
-import classes from "./Button.module.css";
 
-interface BaseProps
-  extends CssProp,
-    AriaProps,
-    ChildrenProp<React.ReactElement<ButtonProps & { value: string }>> {
+interface BaseProps extends CssProp, AriaProps {
   /**
    * vertical orientation
    */
@@ -69,31 +66,61 @@ interface BaseProps
   fullWidth?: boolean;
 }
 
-export type ToggleButtonGroupProps = BaseProps &
-  (
-    | {
-        /**
-         *
-         */
-        value: string;
-        /**
-         * change handler
-         */
-        onChange?: (value: string) => void;
-      }
-    | {
-        /**
-         *
-         */
-        value: string[];
-        /**
-         * change handler
-         */
-        onChange?: (value: string[]) => void;
-      }
-  );
+export type ToggleButtonGroupValueProps<T> =
+  | {
+      /**
+       *
+       */
+      value: T;
+      /**
+       * change handler
+       */
+      onChange?: (value: T | null) => void;
+    }
+  | {
+      /**
+       *
+       */
+      value: T[];
+      /**
+       * change handler
+       */
+      onChange?: (value: T[] | null) => void;
+    };
+
+export type ToggleButtonGroupProps<T> = BaseProps &
+  ChildrenProp<React.ReactElement<ButtonProps & { value: T }>> &
+  ToggleButtonGroupValueProps<T>;
 
-export const ToggleButtonGroup = ({
+/**
+ * A component that groups toggle buttons together, allowing for consistent styling and behavior across multiple toggle buttons.
+ * It supports vertical orientation, various button styles, and can handle properties like size, color, and disabled state.
+ * This component is useful for creating toggle button groups that maintain a uniform appearance and functionality,
+ * such as toggle switches, selection groups, or multi-select options.
+ *
+ * @param {ToggleButtonGroupProps} props - The properties for the ToggleButtonGroup component.
+ * @returns {JSX.Element} The rendered ToggleButtonGroup component.
+ *
+ * @example
+ * ```jsx
+ * <ToggleButtonGroup
+ *   value={selectedValues}
+ *   onChange={(newValues) => setSelectedValues(newValues)}
+ *   variant="outline"
+ *   color="primary"
+ *   size="md"
+ *   rounded
+ *   fullWidth
+ * >
+ *   <Button value="option1">Option 1</Button>
+ *   <Button value="option2">Option 2</Button>
+ *   <Button value="option3">Option 3</Button>
+ * </ToggleButtonGroup>
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/docs/core-components-togglebuttongroup--docs} for more details.
+ */
+export const ToggleButtonGroup = <T extends AnyObject = string>({
   vertical,
   className,
   children,
@@ -106,23 +133,24 @@ export const ToggleButtonGroup = ({
   value,
   onChange,
   ...aria
-}: ToggleButtonGroupProps) => {
-  const isMultiple = useMemo(() => isArray(value), [value]);
-  const { currentValue, updateValue } = useControlledValue<typeof value>(
+}: ToggleButtonGroupProps<T>) => {
+  const { currentValue, updateValue } = useControlledValue(
     value,
-    isArray(value) ? EMPTY_ARRAY : "",
+    isArray(value) ? EMPTY_ARRAY : null,
   );
 
   const clickHandler = useCallback(
-    (cb: AnyObject) => (e: React.MouseEvent<HTMLElement>) => {
-      let newValue: AnyObject = `${e.currentTarget.dataset.value}`;
+    (cb: AnyObject, childValue: T) => (e: React.MouseEvent<HTMLElement>) => {
+      let newValue;
       if (isArray(currentValue)) {
-        if (currentValue.includes(newValue))
-          newValue = currentValue.filter((v) => v !== newValue);
-        else newValue = [...currentValue, newValue];
+        if (currentValue.includes(childValue))
+          newValue = currentValue.filter((v) => v !== childValue);
+        else newValue = [...currentValue, childValue];
+      } else {
+        newValue = childValue;
       }
       updateValue(newValue);
-      onChange?.(newValue);
+      onChange?.(newValue as AnyObject);
       cb?.(e);
     },
     [currentValue, onChange],
@@ -131,16 +159,16 @@ export const ToggleButtonGroup = ({
   return (
     <div
       className={classNames(
-        classes.buttonGroup,
+        "fabric-buttonGroup",
         className,
         fullWidth ? "flex" : "inline-flex",
         "flex-nowrap align-middle",
-        vertical && classes.vertical,
+        vertical && "vertical",
         vertical && "flex-col",
       )}
       {...aria}
     >
-      {Children.map(children, (child: AnyObject) =>
+      {cloneChildren(children, (child: AnyObject) =>
         cloneElement(child, {
           color,
           size,
@@ -149,10 +177,9 @@ export const ToggleButtonGroup = ({
           rounded,
           fullWidth,
           ...child.props,
-          onClick: clickHandler(child.props.onClick),
-          "data-value": child.props.value,
-          "data-checked": isMultiple
-            ? currentValue.includes(child.props.value)
+          onClick: clickHandler(child.props.onClick, child.props.value),
+          "data-checked": isArray(currentValue)
+            ? currentValue?.includes(child.props.value)
             : currentValue === child.props.value,
         }),
       )}

package/src/components/callout/Callout.tsx

@@ -25,13 +25,11 @@ import classNames from "classnames";
 import {
   type AriaProps,
   type ChildrenProp,
-  type ColorType,
+  type ColorState,
   type CssProp,
-  type PaletteType,
   type TestProps,
 } from "../../types";
 import { CoreIcons } from "../../types/icons";
-import { getBgClass, getBorderClass, getColorClass } from "../../utils";
 import { Icon } from "../icon/Icon";
 
 export interface CalloutProps
@@ -42,11 +40,11 @@ export interface CalloutProps
   /**
    * callout color
    */
-  color?: ColorType | PaletteType;
+  color?: ColorState | "none";
   /**
    * legend title
    */
-  legend?: string;
+  legend?: string | React.ReactElement;
   /**
    * callout icon
    */
@@ -65,6 +63,44 @@ export interface CalloutProps
   onClose?: () => void;
 }
 
+// colors for different callout types
+const colors = {
+  none: "bg-base text-tint-900 border-tint-100",
+  tint: "bg-tint-50/50 text-tint-800 border-tint-300",
+  primary: "bg-primary-50/50 text-primary-800 border-primary-300",
+  accent: "bg-accent-50/50 text-accent-800 border-accent-300",
+  info: "bg-info-50/50 text-info-800 border-info-300",
+  danger: "bg-danger-50/50 text-danger-800 border-danger-300",
+  success: "bg-success-50/50 text-success-800 border-success-300",
+  warning: "bg-warning-50/50 text-warning-800 border-warning-300",
+};
+
+/**
+ * A component that displays a callout box with an optional title, icon, and legend.
+ * It can be used to highlight important information, warnings, or notices.
+ * The callout can be styled with different colors and border styles, and it supports a close action.
+ * This component is useful for drawing attention to specific content within a page or application,
+ * such as alerts, notifications, or important messages.
+ *
+ * @param {CalloutProps} props - The properties for the Callout component.
+ * @returns {JSX.Element} The rendered Callout component.
+ *
+ * @example
+ * ```jsx
+ * <Callout
+ *   color="primary"
+ *   legend="Important Notice"
+ *   title="Attention Required"
+ *   icon="info"
+ *   onClose={() => console.log("Callout closed")}
+ * >
+ *   This is an important message that requires your attention.
+ * </Callout>
+ * // Renders a callout box with a primary color, an icon, a title, and a close button.
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/story/core-components-callout--docs} for more details.
+ */
 export const Callout = ({
   children,
   // @ts-expect-error ignore
@@ -80,27 +116,34 @@ export const Callout = ({
   return (
     <fieldset
       className={classNames(
-        className,
         "block rounded-capped border max-w-full relative overflow-hidden mb-4",
-        getBgClass(color + "-50"),
-        getColorClass(color + "-700"),
-        getBorderClass(color + "-300"),
+        colors[color],
+        className,
         border === "dashed" && "border-dashed",
         border === "dotted" && "border-dotted",
       )}
       {...aria}
     >
-      {legend && <legend className="px-2 mx-4 font-medium">{legend}</legend>}
+      {legend && (
+        <legend className="px-2 mx-4 font-medium" data-ref="calloutLegend">
+          {legend}
+        </legend>
+      )}
       <div className={classNames("break-words whitespace-break-spaces p-2")}>
         <div className="flex flex-nowrap items-center text-xl pe-4 gap-2 mb-4 empty:mb-0">
-          {icon && <Icon icon={icon} />}
-          {title && <p className="flex-1">{title}</p>}
+          {icon && <Icon icon={icon} data-ref="calloutIcon" />}
+          {title && (
+            <p className="flex-1" data-ref="calloutTitle">
+              {title}
+            </p>
+          )}
         </div>
         <div className="pe-4">{children}</div>
       </div>
       {onClose && (
         <Icon
           size="md"
+          data-ref="calloutClose"
           className={classNames("absolute end-2", legend ? "top-0" : "top-2")}
           icon={CoreIcons.close}
           onClick={onClose}