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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@react-fabric/core",
-  "version": "1.0.0-beta.6",
+  "version": "1.0.0-beta.61",
   "description": "RUF: Core package",
   "author": "Adarsh Pastakia <adarshpastakia@outlook.com>",
   "license": "MIT",
@@ -35,26 +35,27 @@
     "watch": "npm-run-all -p watch:rollup watch:dts"
   },
   "dependencies": {
-    "@floating-ui/react": "^0.26.24",
-    "@react-fabric/utilities": "^1.0.0-beta.6",
-    "@tailwindcss/container-queries": "^0.1.1",
-    "@tailwindcss/forms": "^0.5.7",
-    "@tailwindcss/typography": "^0.5.13",
-    "boring-avatars": "^1.10.2",
-    "classnames": "^2.5.1",
-    "color": "^4.2.3",
-    "resize-observer-polyfill": "^1.5.1",
-    "tailwindcss": "^3.4.4"
+    "@floating-ui/react": "~0.27.16",
+    "@iconify-json/mdi": "~1.2.3",
+    "@iconify-json/svg-spinners": "~1.2.4",
+    "@iconify/tailwind4": "~1.2.1",
+    "@react-fabric/utilities": "^1.0.0-beta.61",
+    "@tailwindcss/postcss": "~4.1.16",
+    "boring-avatars": "~1.11.2",
+    "classnames": "~2.5.1",
+    "color": "~5.0.2",
+    "resize-observer-polyfill": "~1.5.1",
+    "tailwindcss": "~4.1.16"
   },
   "peerDependencies": {
-    "i18next": "^23.15.1",
-    "react": ">=18.0.0 <20.0.0",
-    "react-dom": ">=18.0.0 <20.0.0",
-    "react-i18next": "^15.0.2"
+    "i18next": "~25.6.0",
+    "react": "~19.2.0",
+    "react-dom": "~19.2.0",
+    "react-i18next": "~16.2.1"
   },
   "engines": {
     "node": ">=18.12.0",
     "npm": ">=8.19.0"
   },
-  "gitHead": "21167df13cedeae8b365e87b9bab6d7401298cb6"
+  "gitHead": "a0b0c571bf9c189fa3355bbc3b896ecc4b9d6a04"
 }

package/src/components/actionLabel/ActionLabel.tsx

@@ -30,7 +30,6 @@ import {
   type TestProps,
 } from "../../types";
 import { ButtonGroup } from "../button/ButtonGroup";
-import classes from "./ActionLabel.module.css";
 
 export interface ActionLabelProps
   extends AriaProps,
@@ -52,8 +51,27 @@ export interface ActionLabelProps
 }
 
 /**
- * A simple label component with additional actions (like a button or icon) that becomes visible only when the user hovers over the label,
- * useful in interfaces where space is limited or where it's important to keep the UI clean and focused
+ * A label with action buttons that can be aligned to the start or end.
+ * This component is useful for displaying a label with associated actions, such as buttons, that can be aligned based on the design requirements.
+ * It automatically calculates the width of the action buttons to ensure that the label text does not overflow the container.
+ * It uses CSS variables to manage the width of the label text dynamically based on the action buttons' width.
+ * This component is designed to be flexible and can be used in various contexts where a label with actions is needed.
+ * It supports custom alignment, disabled states, and can be easily styled with additional CSS classes.
+ *
+ * @param {ActionLabelProps} props - The properties for the ActionLabel component.
+ * @returns {JSX.Element} The rendered ActionLabel component.
+ *
+ * @example
+ * ```jsx
+ * <ActionLabel
+ *   actions={[<Button>Action 1</Button>, <Button>Action 2</Button>]}
+ *   align="end"
+ * >
+ *   Label Text
+ * </ActionLabel>
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/docs/core-components-action-label--docs} for more details.
  */
 export const ActionLabel = ({
   children,
@@ -63,9 +81,8 @@ export const ActionLabel = ({
   disabled,
   ...rest
 }: ActionLabelProps) => {
-  /**
-   * calculate the width of the action box, width will be used for a delayed transition on hover
-   */
+  // Calculate the width of the action buttons to set a CSS variable
+  // This is used to ensure the label text does not overflow the container
   const calculateBasis = useCallback((el: HTMLElement | null) => {
     if (el) {
       const clone = el.cloneNode(true) as HTMLElement;
@@ -84,7 +101,7 @@ export const ActionLabel = ({
     <div
       className={classNames(
         className,
-        classes.actionLabel,
+        "fabric-actionLabel",
         "flex overflow-hidden gap-1 items-center cursor-default select-none",
       )}
       data-disabled={disabled}
@@ -92,8 +109,9 @@ export const ActionLabel = ({
     >
       <ButtonGroup
         ref={calculateBasis}
+        data-inner-clickable
         className={classNames(
-          classes.actions,
+          "fabric-actions",
           "overflow-hidden flex-content",
           align === "end" && "order-2",
         )}

package/src/components/animations/Animations.tsx

@@ -30,21 +30,42 @@ import {
   type CssProp,
   type PaletteType,
 } from "../../types";
-import { getColor, getColorClass } from "../../utils";
-import classes from "./Animations.module.css";
+import { getColor } from "../../utils";
 
 export interface AnimationProps extends CssProp, AriaProps {
   type?: "info" | "check" | "cross" | "question" | "exclaim";
   /**
    * icon color
    */
-  color?: ColorType | PaletteType;
+  color?: ColorType | PaletteType | string;
   /**
    * icon mark color
    */
-  strokeColor?: ColorType | PaletteType;
+  strokeColor?: ColorType | PaletteType | string;
 }
 
+/**
+ * A component that displays an animated indicator with a customizable icon type and colors.
+ * It can be used to indicate various states such as success, error, or information.
+ * The component supports different icon types like check, cross, question, and exclamation.
+ * It also allows customization of the icon color and stroke color.
+ *
+ * @param {AnimationProps} props - The properties for the AnimationIndicator component.
+ * @returns {JSX.Element} The rendered AnimationIndicator component.
+ *
+ * @example
+ * ```jsx
+ * <AnimationIndicator
+ *   type="check"
+ *   color="primary-500"
+ *   strokeColor="primary-700"
+ *   className="my-custom-class"
+ *   aria-label="Loading"
+ * />
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/story/core-components-animations--docs} for more details.
+ */
 export const AnimationIndicator = ({
   className,
   color,
@@ -80,10 +101,9 @@ export const AnimationIndicator = ({
     <svg
       data-ref="animated-indicator"
       className={classNames(
-        classes.checkAnimation,
+        "fabric-checkAnimation",
         className,
         "inline-block rounded-full",
-        color && getColorClass(color),
       )}
       style={styles}
       xmlns="http://www.w3.org/2000/svg"
@@ -91,92 +111,139 @@ export const AnimationIndicator = ({
       aria-hidden="true"
       {...aria}
     >
-      <circle className={classes.circlePart} cx="26" cy="26" r="25" />
+      <circle className={"fabric-circlePart"} cx="26" cy="26" r="25" />
       <path
-        className={classNames(
-          classes.iconPart,
-          getColorClass(strokeColor ?? "invert"),
-        )}
+        className={classNames("fabric-iconPart")}
+        style={{
+          color: strokeColor
+            ? getColor(strokeColor)
+            : "var(--text-color-invert)",
+        }}
         d={path}
       />
     </svg>
   );
 };
 
-export const AnimationBars = ({
-  color = "tint",
+/**
+ * A component that displays a loading animation with a customizable icon, color, size, and mask blur.
+ * It is typically used to indicate loading states in the UI.
+ *
+ * @param {Object} props - The properties for the AnimationLoader component.
+ * @param {ColorType | PaletteType | string} [props.color="tint-500"] - The color of the loader icon.
+ * @param {number | string} [props.size="2rem"] - The size of the loader icon.
+ * @param {string} props.icon - The icon to be displayed as the loader.
+ * @param {"sm" | "md" | "lg"} [props.maskBlur] - The blur effect for the background mask.
+ * @returns {JSX.Element} The rendered AnimationLoader component.
+ */
+export const AnimationLoader = ({
+  color = "tint-500",
   size = "2rem",
+  icon,
+  maskBlur,
 }: {
-  color?: ColorType | string;
+  icon: string;
+  maskBlur?: "sm" | "md" | "lg";
+  color?: ColorType | PaletteType | string;
   size?: number | string;
 }) => {
   return (
     <div
       className={classNames(
         "absolute inset-0 z-10 flex justify-center items-center cursor-wait",
+        maskBlur === "sm" && "backdrop-blur-sm",
+        maskBlur === "md" && "backdrop-blur-md",
+        maskBlur === "lg" && "backdrop-blur-lg",
       )}
     >
       <div
         className={classNames(
-          "outline outline-tint-500/20 p-4 bg-base/50 backdrop-blur-sm rounded",
+          "outline outline-tint-500/20 p-4 bg-tint-50/50 backdrop-blur-sm leading-0 rounded",
         )}
       >
         <div
-          className={classNames(classes.bars, getColorClass(color + "-500/50"))}
-          style={{ width: size }}
+          className={classNames("aspect-square", icon)}
+          style={{ fontSize: size, color: getColor(color) }}
         />
       </div>
     </div>
   );
 };
 
-export const AnimationSpinner = ({
-  color = "tint-700",
-  size = "2rem",
-}: {
-  color?: ColorType | string;
+/**
+ * A component that displays an animated bars loader.
+ * It can be customized with color and size properties.
+ * This component is typically used to indicate loading states in the UI.
+ *
+ * @param {Object} props - The properties for the LoadingBars component.
+ * @param {ColorType | PaletteType | string} [props.color="tint-500"] - The color of the bars.
+ * @param {number | string} [props.size="2rem"] - The size of the bars.
+ * @returns {JSX.Element} The rendered LoadingBars component.
+ *
+ * @example
+ * ```jsx
+ * <LoadingBars color="primary-500" size="3rem" />
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/story/core-components-animations--docs} for more details.
+ */
+export const LoadingBars = (props: {
+  color?: ColorType | PaletteType | string;
   size?: number | string;
+  maskBlur?: "sm" | "md" | "lg";
 }) => {
   return (
-    <div
-      className={classNames(
-        "absolute inset-0 z-10 flex justify-center items-center cursor-wait",
-      )}
-      data-testid="spinner"
-    >
-      <div
-        className={classNames(
-          "outline outline-tint-500/20 p-4 bg-base/50 backdrop-blur-sm rounded",
-        )}
-      >
-        <div
-          className={classNames(classes.spinner, getColorClass(color))}
-          style={{ width: size }}
-        />
-      </div>
-    </div>
+    <AnimationLoader icon="icon-[svg-spinners--bars-scale-fade]" {...props} />
   );
 };
 
-export const Loading = () => {
-  return (
-    <div
-      className={classNames(
-        classes.loader,
-        "area-[loader] relative overflow-x-clip",
-      )}
-      data-testid="loading"
-    >
-      <div className="absolute z-10 py-px inset-x-0 top-0 after:h-0.5 after:block after:bg-primary-500" />
-    </div>
-  );
+/**
+ * A component that displays a spinner animation.
+ * It can be customized with color and size properties.
+ * This component is typically used to indicate loading states in the UI.
+ *
+ * @param {Object} props - The properties for the LoadingSpinner component.
+ * @param {ColorType | PaletteType | string} [props.color="tint-700"] - The color of the spinner.
+ * @param {number | string} [props.size="2rem"] - The size of the spinner.
+ * @returns {JSX.Element} The rendered LoadingSpinner component.
+ *
+ * @example
+ * ```jsx
+ * <LoadingSpinner color="primary-500" size="3rem" />
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/story/core-components-animations--docs} for more details.
+ */
+export const LoadingSpinner = (props: {
+  color?: ColorType | PaletteType | string;
+  size?: number | string;
+  maskBlur?: "sm" | "md" | "lg";
+}) => {
+  return <AnimationLoader icon="icon-[svg-spinners--eclipse]" {...props} />;
 };
 
+/**
+ * A component that displays a skeleton loader with a placeholder for content.
+ * It can be customized with color and size properties.
+ * This component is typically used to indicate loading states in the cards, panels and virtual lists,
+ * providing a visual placeholder for content that is being loaded.
+ *
+ * @param {CssProp} props - The properties for the Skeleton component.
+ * @returns {JSX.Element} The rendered Skeleton component.
+ *
+ * @example
+ * ```jsx
+ * <Skeleton className="my-skeleton" />
+ * * // Renders a skeleton loader with a placeholder for content.
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/story/core-components-animations--docs} for more details.
+ */
 export const Skeleton = ({ className, ...rest }: CssProp) => {
   return (
     <div
       className={classNames(className, "p-2 animate-pulse flex gap-2 max-w-lg")}
-      data-testid="skeleton"
+      data-ref="skeleton"
       {...rest}
     >
       <div className="bg-tint-100 rounded aspect-square h-12" />
@@ -194,3 +261,23 @@ export const Skeleton = ({ className, ...rest }: CssProp) => {
     </div>
   );
 };
+
+/**
+ * A component that displays a loading animation with a top border.
+ * It is typically used to indicate that content is being loaded in pages and page sections.
+ *
+ * @returns {JSX.Element} The rendered Loading component.
+ */
+export const LoadingLine = () => {
+  return (
+    <div
+      className={classNames(
+        "fabric-loader",
+        "area-[loader] relative overflow-x-clip",
+      )}
+      data-ref="loading"
+    >
+      <div className="absolute z-10 py-px inset-x-0 top-0 after:h-0.5 after:block after:bg-primary-500" />
+    </div>
+  );
+};

package/src/components/avatar/Avatar.tsx

@@ -26,6 +26,7 @@ import BoringAvatar from "boring-avatars";
 import classNames from "classnames";
 import { useMemo, useState } from "react";
 import {
+  type PaletteType,
   type AriaProps,
   type ColorType,
   type CssProp,
@@ -33,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 {
   /**
@@ -56,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
    */
@@ -73,6 +73,10 @@ export interface AvatarProps extends CssProp, AriaProps, TestProps, RefProp {
    * rounded icon
    */
   rounded?: boolean;
+  /**
+   * prevent click default, useful when component is within a `a` link
+   */
+  preventDefault?: boolean;
   /**
    * click handler
    */
@@ -88,7 +92,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,
@@ -102,12 +131,14 @@ export const Avatar = ({
   variant = "beam",
   className,
   viewBox = "0 0 24 24",
+  preventDefault,
   onClick,
   ...aria
 }: AvatarProps) => {
   const [fallback, setFallback] = useState(true);
 
-  /** ***************** style map *******************/
+  // Memoize styles to avoid unnecessary recalculations
+  // and to ensure styles are only recalculated when dependencies change
   const styles = useMemo(() => {
     const s: KeyValue = {};
     if (bg) {
@@ -125,7 +156,8 @@ export const Avatar = ({
     return s;
   }, [bg, color, size]);
 
-  /** ***************** render icon *******************/
+  // avatar image
+  // if avatar is not provided, fallback to icon or text
   const avatarImage = useMemo(() => {
     setFallback(!avatar);
     return (
@@ -133,7 +165,7 @@ export const Avatar = ({
         <div className="contents">
           <div
             className={classNames(
-              classes.imgPlaceholder,
+              "fabric-imgPlaceholder",
               "absolute inset-0 bg-gray animate-pulse",
             )}
           />
@@ -149,10 +181,11 @@ export const Avatar = ({
     );
   }, [avatar]);
 
+  // render fallback icon or text
   const fallbackAvatar = useMemo(() => {
     if (fallbackIcon) {
       return isSvgPath(fallbackIcon) ? (
-        <svg viewBox={viewBox}>
+        <svg viewBox={viewBox} className="p-[0.125em]">
           <path fill="currentColor" d={fallbackIcon.toString()} />
         </svg>
       ) : (
@@ -160,8 +193,9 @@ export const Avatar = ({
       );
     }
     if (variant === "text") {
-      const [, first, second, group] =
-        name.match(/(?=(\w).* (\w).*)|(?=(\w\w).*)/) ?? [];
+      const [, first, second, group] = name.match(
+        /(?=(\w).* (\w).*)|(?=(\w\w).*)/,
+      ) as string[];
       return (
         <svg role="img">
           <text
@@ -177,6 +211,7 @@ export const Avatar = ({
         </svg>
       );
     }
+    // Fallback to BoringAvatar
     return <BoringAvatar square size={64} variant={variant} name={name} />;
   }, [name, variant, fallbackIcon]);
 
@@ -184,15 +219,16 @@ export const Avatar = ({
     <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",
       )}
-      onClick={onClick}
+      onClick={(e) => {
+        preventDefault && e.preventDefault();
+        onClick?.(e);
+      }}
       style={styles}
       data-clickable={!!onClick}
       ref={ref}

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>