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

package/src/components/avatar/Avatar.tsx

@@ -24,9 +24,9 @@
 import { isSvgPath } from "@react-fabric/utilities";
 import BoringAvatar from "boring-avatars";
 import classNames from "classnames";
-import { useState } from "react";
-import { useMemoDebugger } from "../../hooks/useEffectDebugger";
+import { useMemo, useState } from "react";
 import {
+  type PaletteType,
   type AriaProps,
   type ColorType,
   type CssProp,
@@ -34,8 +34,7 @@ import {
   type SizeType,
   type TestProps,
 } from "../../types";
-import { getBgClass, getColor, getColorClass } from "../../utils";
-import classes from "./Avatar.module.css";
+import { getColor } from "../../utils";
 
 export interface AvatarProps extends CssProp, AriaProps, TestProps, RefProp {
   /**
@@ -57,11 +56,11 @@ export interface AvatarProps extends CssProp, AriaProps, TestProps, RefProp {
   /**
    * background color (CSS color / tailwind color)
    */
-  bg?: ColorType | string;
+  bg?: ColorType | PaletteType | string;
   /**
    * icon color (CSS color / tailwind color)
    */
-  color?: ColorType | string;
+  color?: ColorType | PaletteType | string;
   /**
    * icon size
    */
@@ -89,7 +88,32 @@ const SizeMap: KeyValue<string> = {
 };
 
 /**
- * An avatar is a graphical representation of a user's identity.
+ * A component that displays an avatar image or a fallback icon with customizable styles and properties.
+ * It supports various avatar types, including text-based avatars, and allows for customization of background color, icon color, size, and rounded corners.
+ * This component is useful for displaying user avatars in applications, providing a visual representation of users or entities.
+ * It can also handle cases where the avatar image fails to load by displaying a fallback icon or text.
+ * It uses the Boring Avatars library for generating fallback avatars based on the user's name.
+ *
+ * @param {AvatarProps} props - The properties for the Avatar component.
+ * @returns {JSX.Element} The rendered Avatar component.
+ *
+ * @example
+ * ```jsx
+ * <Avatar
+ *   name="John Doe"
+ *   avatar="https://example.com/avatar.jpg"
+ *   fallbackIcon="fas fa-user"
+ *   bg="bg-blue-500"
+ *   color="text-white"
+ *   size="md"
+ *   rounded
+ *   variant="beam"
+ *   onClick={() => console.log("Avatar clicked")}
+ * />
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/story/core-components-avatar--docs} for more details.
+ * @see {@link https://boringavatars.com/} for more information on Boring Avatars.
  */
 export const Avatar = ({
   ref,
@@ -108,100 +132,91 @@ export const Avatar = ({
 }: AvatarProps) => {
   const [fallback, setFallback] = useState(true);
 
-  /** ***************** style map *******************/
-  const styles = useMemoDebugger(
-    () => {
-      const s: KeyValue = {};
-      if (bg) {
-        s.backgroundColor = getColor(bg);
-      }
-      if (color) {
-        s.color = getColor(color);
-      }
-      if (size && !(size in SizeMap)) {
-        s.fontSize = size;
-      }
-      if (size && size in SizeMap) {
-        s.fontSize = SizeMap[size];
-      }
-      return s;
-    },
-    [bg, color, size],
-    "Avatar styles",
-  );
+  // Memoize styles to avoid unnecessary recalculations
+  // and to ensure styles are only recalculated when dependencies change
+  const styles = useMemo(() => {
+    const s: KeyValue = {};
+    if (bg) {
+      s.backgroundColor = getColor(bg);
+    }
+    if (color) {
+      s.color = getColor(color);
+    }
+    if (size && !(size in SizeMap)) {
+      s.fontSize = size;
+    }
+    if (size && size in SizeMap) {
+      s.fontSize = SizeMap[size];
+    }
+    return s;
+  }, [bg, color, size]);
+
+  // avatar image
+  // if avatar is not provided, fallback to icon or text
+  const avatarImage = useMemo(() => {
+    setFallback(!avatar);
+    return (
+      avatar && (
+        <div className="contents">
+          <div
+            className={classNames(
+              "fabric-imgPlaceholder",
+              "absolute inset-0 bg-gray animate-pulse",
+            )}
+          />
+          <img
+            src={avatar}
+            alt={avatar}
+            className="align-baseline"
+            onError={() => setFallback(true)}
+            onLoad={(e) => e.currentTarget.previousElementSibling?.remove()}
+          />
+        </div>
+      )
+    );
+  }, [avatar]);
 
-  /** ***************** render icon *******************/
-  const avatarImage = useMemoDebugger(
-    () => {
-      setFallback(!avatar);
+  // render fallback icon or text
+  const fallbackAvatar = useMemo(() => {
+    if (fallbackIcon) {
+      return isSvgPath(fallbackIcon) ? (
+        <svg viewBox={viewBox}>
+          <path fill="currentColor" d={fallbackIcon.toString()} />
+        </svg>
+      ) : (
+        <i className={fallbackIcon} />
+      );
+    }
+    if (variant === "text") {
+      const [, first, second, group] = name.match(
+        /(?=(\w).* (\w).*)|(?=(\w\w).*)/,
+      ) as string[];
       return (
-        avatar && (
-          <div className="contents">
-            <div
-              className={classNames(
-                classes.imgPlaceholder,
-                "absolute inset-0 bg-gray animate-pulse",
-              )}
-            />
-            <img
-              src={avatar}
-              alt={avatar}
-              className="align-baseline"
-              onError={() => setFallback(true)}
-              onLoad={(e) => e.currentTarget.previousElementSibling?.remove()}
-            />
-          </div>
-        )
+        <svg role="img">
+          <text
+            x="50%"
+            y="50%"
+            dy=".1em"
+            dominantBaseline="middle"
+            textAnchor="middle"
+            style={{ fontSize: ".5em", fontWeight: 500 }}
+          >
+            {group ?? `${first}${second}`}
+          </text>
+        </svg>
       );
-    },
-    [avatar],
-    "Avatar icon",
-  );
-
-  const fallbackAvatar = useMemoDebugger(
-    () => {
-      if (fallbackIcon) {
-        return isSvgPath(fallbackIcon) ? (
-          <svg viewBox={viewBox}>
-            <path fill="currentColor" d={fallbackIcon.toString()} />
-          </svg>
-        ) : (
-          <i className={fallbackIcon} />
-        );
-      }
-      if (variant === "text") {
-        const [, first, second, group] =
-          name.match(/(?=(\w).* (\w).*)|(?=(\w\w).*)/) ?? [];
-        return (
-          <svg role="img">
-            <text
-              x="50%"
-              y="50%"
-              dy=".1em"
-              dominantBaseline="middle"
-              textAnchor="middle"
-              style={{ fontSize: ".5em", fontWeight: 500 }}
-            >
-              {group ?? `${first}${second}`}
-            </text>
-          </svg>
-        );
-      }
-      return <BoringAvatar square size={64} variant={variant} name={name} />;
-    },
-    [name, variant, fallbackIcon],
-    "Avatar fallback",
-  );
+    }
+    // Fallback to BoringAvatar
+    return <BoringAvatar square size={64} variant={variant} name={name} />;
+  }, [name, variant, fallbackIcon]);
 
   return (
     <dfn
       role="presentation"
       className={classNames(
-        classes.avatar,
+        "fabric-avatar",
         className,
         "select-none relative overflow-hidden inline-block box-content leading-none not-italic text-center",
-        bg && getBgClass(bg),
-        color && getColorClass(color),
         !rounded && "rounded",
         rounded && "rounded-full",
       )}

package/src/components/avatar/AvatarGroup.tsx

@@ -31,7 +31,6 @@ import {
   type SizeType,
 } from "../../types";
 import { type AvatarProps } from "./Avatar";
-import classes from "./Avatar.module.css";
 
 type AvatarChild =
   | ReactElement<Omit<AvatarProps, "size" | "rounded">>
@@ -63,7 +62,25 @@ const SizeMap: KeyValue<string> = {
 };
 
 /**
- * Group multiple avatars together
+ * A component that groups multiple avatars together, displaying a count of additional avatars if the total exceeds the visible ones.
+ * It allows customization of size, rounding, and additional aria attributes.
+ * This component is useful for displaying a collection of user avatars in a compact format, such as in a chat application or user list.
+ * It automatically calculates the number of additional avatars based on the `totalCount` prop and the number of children provided.
+ *
+ * @param {AvatarGroupProps} props - The properties for the AvatarGroup component.
+ * @returns {JSX.Element} The rendered AvatarGroup component.
+ *
+ * @example
+ * ```jsx
+ * <AvatarGroup totalCount={5} size="md" className="my-avatar-group">
+ *   <Avatar name="John Doe" avatar="https://example.com/avatar1.jpg" />
+ *   <Avatar name="Jane Smith" avatar="https://example.com/avatar2.jpg" />
+ *   <Avatar name="Alice Johnson" avatar="https://example.com/avatar3.jpg" />
+ *   <Avatar name="Bob Brown" avatar="https://example.com/avatar4.jpg" />
+ * </AvatarGroup>
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/docs/core-components-avatar--docs} for more details.
  */
 export const AvatarGroup = ({
   ref,
@@ -104,7 +121,7 @@ export const AvatarGroup = ({
       {...aria}
       ref={ref as AnyObject}
       className={classNames(
-        classes.avatarGroup,
+        "fabric-avatarGroup",
         className,
         "inline-flex flex-nowrap",
         !rounded && "rounded",
@@ -115,10 +132,11 @@ export const AvatarGroup = ({
       {avatars}
       {!!diff && (
         <dfn
+          data-ref="avatarCount"
           className={classNames(
-            classes.avatar,
+            "fabric-avatar",
             "select-none relative overflow-hidden inline-block box-content leading-none not-italic text-center",
-            classes.extra,
+            "fabric-avatarGroup--extra",
           )}
         >
           <svg>

package/src/components/badge/Badge.tsx

@@ -23,7 +23,7 @@
 
 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,
@@ -32,7 +32,6 @@ import {
   type RefProp,
 } from "../../types";
 import { Icon } from "../icon/Icon";
-import classes from "./Badge.module.css";
 
 export interface BadgeProps
   extends CssProp,
@@ -43,6 +42,10 @@ export interface BadgeProps
    * make wrapper a block element
    */
   block?: boolean;
+  /**
+   * inline badge
+   */
+  inline?: boolean;
   /**
    * badge value
    */
@@ -69,10 +72,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 +93,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,6 +118,7 @@ export const Badge = ({
   max,
   ping,
   block,
+  inline,
   placement = "top-end",
   children,
   // @ts-expect-error ignore
@@ -101,6 +130,9 @@ export const Badge = ({
   ...rest
 }: BadgeProps) => {
   const label = useMemo(() => {
+    if (isValidElement(value)) {
+      return value;
+    }
     if (!isNil(value)) {
       if (isNumber(value) && max && value > max) {
         return `${max}+`;
@@ -120,8 +152,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,16 +161,16 @@ 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" : "absolute",
           )}
         >
           {label && <span className="p-1">{label}</span>}

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,
@@ -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}