@react-fabric/core 1.0.0-beta.6 → 1.0.0-beta.61

package/src/components/badge/Badge.tsx

@@ -23,30 +23,32 @@
 
 import { isNil, isNumber, isObject, mergeRefs } from "@react-fabric/utilities";
 import classNames from "classnames";
-import { cloneElement, useMemo } from "react";
+import { cloneElement, isValidElement, useMemo } from "react";
 import {
   type BadgeType,
   type ChildProp,
   type CssProp,
-  type IconProps,
   type RefProp,
 } from "../../types";
-import { Icon } from "../icon/Icon";
-import classes from "./Badge.module.css";
+import { getIconProps, Icon, type IconProps } from "../icon/Icon";
 
-export interface BadgeProps
-  extends CssProp,
-    RefProp,
-    IconProps,
-    Partial<ChildProp> {
+export interface BadgeProps extends CssProp, RefProp, Partial<ChildProp> {
   /**
    * make wrapper a block element
    */
   block?: boolean;
+  /**
+   * inline badge
+   */
+  inline?: boolean;
   /**
    * badge value
    */
   value?: number | string;
+  /**
+   * icon path or props
+   */
+  icon?: IconProps;
   /**
    * max value for number display
    */
@@ -69,10 +71,17 @@ export interface BadgeProps
     | "end";
 }
 
+/**
+ * Utility function to get badge properties from a badge value or object.
+ * It checks if the badge is an object and returns its properties,
+ *
+ * @param {string | number | BadgeType} badge - The badge value or object.
+ * @returns {AnyObject} An object containing badge properties.
+ */
 export const getBadgeProps = (
   badge?: string | number | BadgeType,
 ): AnyObject => {
-  if (isObject(badge)) {
+  if (isObject(badge) && !isValidElement(badge)) {
     return Object.assign({ forButton: true, placement: "" }, badge);
   } else {
     return {
@@ -83,6 +92,24 @@ export const getBadgeProps = (
   }
 };
 
+/**
+ * A component that displays a badge with a value, icon, and optional ping animation.
+ * It can be used to indicate notifications, messages, or other important information.
+ * It supports various placements, inline or block display, and custom styling.
+ * It can also wrap children elements, allowing for flexible usage in buttons or other components.
+ *
+ * @param {BadgeProps} props - The properties for the Badge component.
+ * @returns {JSX.Element} The rendered Badge component.
+ *
+ * @example
+ * ```jsx
+ * <Badge value={5} max={10} ping>
+ *   <button>Notifications</button>
+ * </Badge>
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/docs/core-components-badge--docs} for more details.
+ */
 export const Badge = ({
   ref,
   className,
@@ -90,17 +117,18 @@ export const Badge = ({
   max,
   ping,
   block,
+  inline,
   placement = "top-end",
   children,
   // @ts-expect-error ignore
   forButton = false,
   icon,
-  iconBg,
-  iconColor,
-  rtlFlip,
   ...rest
 }: BadgeProps) => {
   const label = useMemo(() => {
+    if (isValidElement(value)) {
+      return value;
+    }
     if (!isNil(value)) {
       if (isNumber(value) && max && value > max) {
         return `${max}+`;
@@ -120,8 +148,8 @@ export const Badge = ({
   return (
     <div
       className={classNames(
-        forButton ? "contents" : "relative",
-        block ? "block" : "inline-block",
+        forButton || inline ? "contents" : block ? "block" : "inline-block",
+        forButton || inline ? "" : "relative",
       )}
     >
       {children &&
@@ -129,22 +157,22 @@ export const Badge = ({
           ...rest,
           ref: innerRef,
         })}
-      {(!!ping || label) && (
+      {(!!ping || (label ?? icon)) && (
         <div
           data-ref="badge"
           data-ping={ping}
           data-placement={placement}
           className={classNames(
-            classes.badge,
+            "fabric-badge",
             className,
-            "inline-block p-px min-w-2 min-h-2 text-center select-none rounded-full leading-none z-5 pointer-events-none",
-            forButton && !placement ? "relative" : "absolute",
+            "inline-block p-px min-w-2 min-h-2 text-center select-none rounded-full leading-none z-2 pointer-events-none",
+            (forButton && !placement) || inline
+              ? "relative flex-content"
+              : "absolute",
           )}
         >
           {label && <span className="p-1">{label}</span>}
-          {icon && (
-            <Icon icon={icon} bg={iconBg} color={iconColor} rtlFlip={rtlFlip} />
-          )}
+          {icon && <Icon {...getIconProps(icon)} />}
         </div>
       )}
     </div>

package/src/components/breadcrumbs/Breadcrumbs.tsx

@@ -24,14 +24,13 @@
 import classNames from "classnames";
 import { Children, useMemo } from "react";
 import { type AriaProps, type ChildrenProp, type CssProp } from "../../types";
-import { Link } from "../../typography/Link";
+import { Anchor } from "../../typography/Anchor";
 import { Dropdown } from "../dropdown/Dropdown";
-import classes from "./Breadcrumbs.module.css";
 
 export interface BreadcrumbProps
   extends CssProp,
     AriaProps,
-    ChildrenProp<typeof Link> {
+    ChildrenProp<typeof Anchor> {
   /**
    * breadcrumb styling
    */
@@ -46,6 +45,35 @@ export interface BreadcrumbProps
   color?: "primary" | "accent";
 }
 
+/**
+ * A navigation component that displays the current page's location within a hierarchy and allows users to navigate back to previous pages.
+ * It supports different styles, separators, and colors, and can handle a variable number of breadcrumb links.
+ * This component is useful for enhancing user navigation experience in applications with multiple levels of content hierarchy.
+ * It automatically manages the display of overflow items when there are too many links to fit in the available space, providing a dropdown for additional links.
+ *
+ * @param {BreadcrumbProps} props - The properties for the Breadcrumbs component.
+ * @returns {JSX.Element} The rendered Breadcrumbs component.
+ *
+ * @example
+ * ```jsx
+ * <Breadcrumbs
+ *   variant="classic"
+ *   separator=">"
+ *   color="primary"
+ *   className="my-custom-class"
+ *   aria-label="Breadcrumbs"
+ * >
+ *   <Anchor href="/">Home</Anchor>
+ *   <Anchor href="/products">Products</Anchor>
+ *   <Anchor href="/products/shoes">Shoes</Anchor>
+ *   <Anchor href="/products/shoes/sneakers">Sneakers</Anchor>
+ *   <Anchor href="/products/shoes/sneakers/nike">Nike</Anchor>
+ *   <Anchor href="/products/shoes/sneakers/nike/airmax">Air Max</Anchor>
+ * </Breadcrumbs>
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/docs/core-components-breadcrumbs--docs} for more details.
+ */
 export const Breadcrumbs = ({
   variant = "classic",
   className,
@@ -55,7 +83,7 @@ export const Breadcrumbs = ({
   ...aria
 }: BreadcrumbProps) => {
   const [start, overflow, end] = useMemo(() => {
-    const nodeList = Children.toArray(children as AnyObject);
+    const nodeList = Children.toArray(children as AnyObject).filter(Boolean);
     if (nodeList.length > 7) {
       return [nodeList.slice(0, 3), nodeList.slice(3, -3), nodeList.slice(-3)];
     }
@@ -64,10 +92,11 @@ export const Breadcrumbs = ({
 
   return (
     <nav
+      data-ref="breadcrumbs"
       data-color={color}
       data-variant={variant}
       className={classNames(
-        classes.breadcrumbs,
+        "fabric-breadcrumbs",
         className,
         "flex flex-nowrap items-center",
       )}
@@ -76,7 +105,7 @@ export const Breadcrumbs = ({
       {start.map((link, idx) => (
         <li
           key={idx}
-          className={classes.breadcrumbLink}
+          className={"fabric-breadcrumbLink"}
           data-separator={separator}
         >
           {link}
@@ -84,12 +113,16 @@ export const Breadcrumbs = ({
       ))}
       {overflow && (
         <Dropdown closeOnClick showArrow>
-          <li className={classes.breadcrumbLink} data-separator={separator}>
-            <Link>...</Link>
+          <li
+            className={"fabric-breadcrumbLink"}
+            data-separator={separator}
+            data-ref="breadcrumbOverflow"
+          >
+            <Anchor data->...</Anchor>
           </li>
           <div
             data-color={color}
-            className={classNames(classes.breadcrumbOverflow, "flex flex-col")}
+            className={classNames("fabric-breadcrumbOverflow", "flex flex-col")}
           >
             {overflow}
           </div>
@@ -98,7 +131,7 @@ export const Breadcrumbs = ({
       {end?.map((link, idx) => (
         <li
           key={idx}
-          className={classes.breadcrumbLink}
+          className={"fabric-breadcrumbLink"}
           data-separator={separator}
         >
           {link}

package/src/components/button/Button.tsx

@@ -21,17 +21,17 @@
  * 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 { isNil, isObject, isString, mergeRefs } from "@react-fabric/utilities";
 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";
@@ -42,26 +42,20 @@ import {
   type AriaProps,
   type BadgeType,
   type CallbackReturn,
-  type ColorType,
+  type ColorState,
   type CssProp,
-  type IconProps,
   type PolymorphicProps,
   type RefProp,
   type SizeType,
   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";
+import { getIconProps, Icon, type IconProps } from "../icon/Icon";
 
-export interface BaseProps
-  extends CssProp,
-    AriaProps,
-    IconProps,
-    RefProp,
-    TestProps {
+export interface BaseProps extends CssProp, AriaProps, RefProp, TestProps {
   /**
    * primary icon alignment
    */
@@ -77,7 +71,11 @@ export interface BaseProps
   /**
    * button color
    */
-  color?: ColorType;
+  color?: ColorState;
+  /**
+   * icon path or props
+   */
+  icon?: IconProps;
   /**
    * button type
    */
@@ -85,7 +83,7 @@ export interface BaseProps
   /**
    * button styling
    */
-  variant?: "outline" | "solid" | "link";
+  variant?: "outline" | "soft" | "solid" | "link";
   /**
    * active state with click disabled
    */
@@ -136,6 +134,10 @@ export interface BaseProps
    */
   hotKey?: string;
 
+  /**
+   * prevent click default, useful when button is within a `a` link
+   */
+  preventDefault?: boolean;
   stopPropagation?: boolean;
 
   onMouseOut?: MouseEventHandler;
@@ -147,12 +149,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,
@@ -160,13 +187,10 @@ export const Button = <Tag extends React.ElementType = "button">({
   children,
   className,
   active,
-  color = "primary",
+  color = "default",
   icon,
-  iconBg,
-  iconColor,
   iconAlign = "start",
   altIcon,
-  rtlFlip,
   rounded,
   size,
   disabled,
@@ -177,6 +201,7 @@ export const Button = <Tag extends React.ElementType = "button">({
   spinOnHover,
   onClick,
   actionMessage,
+  preventDefault,
   stopPropagation,
   type = "button",
   hotKey,
@@ -186,14 +211,16 @@ 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);
+      preventDefault && e.preventDefault();
       stopPropagation && e.stopPropagation();
       const ret = onClick?.(e);
       void Promise.resolve(ret).then((b) => {
@@ -203,7 +230,14 @@ export const Button = <Tag extends React.ElementType = "button">({
         }
       });
     },
-    [onClick, disabled, actionMessage, showActionDoneEvent, stopPropagation],
+    [
+      onClick,
+      disabled,
+      preventDefault,
+      actionMessage,
+      showActionDoneEvent,
+      stopPropagation,
+    ],
   );
 
   /** ***************** reset done state on timeout *******************/
@@ -230,7 +264,7 @@ export const Button = <Tag extends React.ElementType = "button">({
       return {
         content: actionMessage,
         placement: "top",
-        color,
+        color: `${color}-100`,
         open: true,
       } as TooltipType;
     }
@@ -240,11 +274,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 +292,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,29 +317,26 @@ export const Button = <Tag extends React.ElementType = "button">({
         >
           {icon && (
             <Icon
-              className={classes.buttonIcon}
-              icon={icon}
-              bg={iconBg}
-              color={iconColor}
-              rtlFlip={rtlFlip}
+              className={"fabric-buttonIcon"}
               data-align={iconAlign}
+              {...getIconProps(icon)}
             />
           )}
           {isValidElement(children) && (
-            <div className={classes.buttonChild}>{children}</div>
+            <div className={"fabric-buttonChild"}>{children}</div>
           )}
           {isString(children) && (
             <label
-              className={classNames(classes.buttonLabel, "truncate")}
-              data-colored-icon={!!iconBg}
+              className={classNames("fabric-buttonLabel", "truncate")}
+              data-colored-icon={isObject(icon) && "bg" in icon}
             >
               {children}
             </label>
           )}
           {!isNil(badge) && <Badge {...badgeProps} />}
-          {hotKey && <HotKeyLabel keyCombo={hotKey} />}
+          {hotKey && children && <HotKeyLabel keyCombo={hotKey} />}
           {altIcon && (
-            <Icon className={classes.altIcon} icon={altIcon} rtlFlip />
+            <Icon className={"fabric-altIcon"} icon={altIcon} rtlFlip />
           )}
         </E>
       </TooltipWrapper>
@@ -314,9 +344,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

@@ -80,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,
@@ -187,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)]}
                   >
@@ -206,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")}