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

package/dist/types/typography/Text.d.ts

@@ -30,6 +30,32 @@ export interface TextProps extends ChildrenProp, CssProp, AriaProps, TestProps {
     clamp?: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
 }
 /**
- * Typography text component
+ * A component that renders text with various styles, supports line clamping, and provides a "show more" link if the text is clipped.
+ * It can be rendered as an inline element or a block element, and allows customization of background color, text color, font size, font family, and text alignment.
+ * It also supports line clamping to limit the number of visible lines, and provides a toggle to show more or less text when the content exceeds the specified clamp.
+ * The component uses a combination of CSS and JavaScript to achieve the desired effects, ensuring a smooth user experience.
+ * It leverages the ResizeObserver API to detect changes in the text container's size and adjust the line clamping accordingly.
+ *
+ * @param {TextProps} props - The properties for the Text component.
+ * @returns {JSX.Element} The rendered Text component.
+ *
+ * @example
+ * ```jsx
+ * <Text
+ *   inline={false}
+ *   bg="bg-gray-100"
+ *   color="text-gray-800"
+ *   size="md"
+ *   family="sans"
+ *   clamp={2}
+ *   align="start"
+ * >
+ *   This is a sample text that demonstrates the Text component with various styles applied.
+ * </Text>
+ * // Renders a block-level text with gray background, dark gray text, medium font size,
+ * // sans-serif font family, clamped to 2 lines, and left-aligned.
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/story/core-typography--text} for more details.
  */
 export declare const Text: ({ children, className, inline, bg, color, family, size, clamp, align, ...aria }: TextProps) => import("react/jsx-runtime").JSX.Element;

package/dist/types/typography/Title.d.ts

@@ -24,6 +24,21 @@ export interface TitleProps extends ChildrenProp, CssProp, AriaProps {
     align?: "start" | "end" | "center" | "justify";
 }
 /**
- * Typography title component
+ * A component that renders a title with customizable styles such as background color, text color, size, alignment, and font family.
+ * It can be rendered as different HTML elements based on the `as` prop.
+ * This component is useful for creating headings or titles in a consistent style across an application.
+ *
+ * @param {TitleProps} props - The properties for the Title component.
+ * @returns {JSX.Element} The rendered Title component.
+ *
+ * @example
+ * ```jsx
+ * <Title as="h1" bg="blue-500" color="white" size="2xl" align="center">
+ *   This is a Title
+ * </Title>
+ * // Renders a title as an h1 element with a blue background, white text color, size of 2xl, and centered alignment.
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/story/core-typography--title} for more details.
  */
 export declare const Title: ({ children, className, as, bg, color, size, align, family, ...aria }: TitleProps) => import("react/jsx-runtime").JSX.Element;

package/dist/types/typography/index.d.ts

@@ -1,6 +1,6 @@
 export { Abbr } from "./Abbr";
+export { Anchor } from "./Anchor";
 export { Copy } from "./Copy";
-export { Link } from "./Link";
 export { Mark } from "./Mark";
 export { Text } from "./Text";
 export { Title } from "./Title";

package/dist/types/utils/cloneElement.d.ts

@@ -0,0 +1 @@
+export declare const cloneChildren: (children: React.ReactNode, callback: (child: React.ReactNode, index: number) => React.ReactNode) => React.ReactNode;

package/dist/types/utils/getColor.d.ts

@@ -1,4 +1 @@
-export declare const getColor: (color: string) => string | undefined;
-export declare const getBgClass: (bg: string) => string | undefined;
-export declare const getColorClass: (color: string) => string | undefined;
-export declare const getBorderClass: (color: string) => string | undefined;
+export declare const getColor: (color: string) => string;

package/dist/types/utils/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./calculateDimensions";
+export * from "./cloneElement";
 export * from "./getColor";
 export * from "./nodeCheck";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@react-fabric/core",
-  "version": "1.0.0-beta.6",
+  "version": "1.0.0-beta.60",
   "description": "RUF: Core package",
   "author": "Adarsh Pastakia <adarshpastakia@outlook.com>",
   "license": "MIT",
@@ -35,26 +35,24 @@
     "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",
+    "@react-fabric/utilities": "^1.0.0-beta.60",
+    "@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": "a79f053ee7e13422c06d7d9c35d4f0c2610cdf5d"
 }

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,23 +111,42 @@ 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>
   );
 };
 
+/**
+ * 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 AnimationBars 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 AnimationBars component.
+ *
+ * @example
+ * ```jsx
+ * <AnimationBars color="primary-500" size="3rem" />
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/story/core-components-animations--docs} for more details.
+ */
 export const AnimationBars = ({
-  color = "tint",
+  color = "tint-500",
   size = "2rem",
 }: {
-  color?: ColorType | string;
+  color?: ColorType | PaletteType | string;
   size?: number | string;
 }) => {
   return (
@@ -118,23 +157,40 @@ export const AnimationBars = ({
     >
       <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 rounded",
         )}
       >
         <div
-          className={classNames(classes.bars, getColorClass(color + "-500/50"))}
-          style={{ width: size }}
+          className={classNames("fabric-bars")}
+          style={{ width: size, color: getColor(color) }}
         />
       </div>
     </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 AnimationSpinner 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 AnimationSpinner component.
+ *
+ * @example
+ * ```jsx
+ * <AnimationSpinner color="primary-500" size="3rem" />
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/story/core-components-animations--docs} for more details.
+ */
 export const AnimationSpinner = ({
   color = "tint-700",
   size = "2rem",
 }: {
-  color?: ColorType | string;
+  color?: ColorType | PaletteType | string;
   size?: number | string;
 }) => {
   return (
@@ -142,41 +198,44 @@ export const AnimationSpinner = ({
       className={classNames(
         "absolute inset-0 z-10 flex justify-center items-center cursor-wait",
       )}
-      data-testid="spinner"
+      data-ref="spinner"
     >
       <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 rounded",
         )}
       >
         <div
-          className={classNames(classes.spinner, getColorClass(color))}
-          style={{ width: size }}
+          className={classNames("fabric-spinner")}
+          style={{ width: size, color: getColor(color) }}
         />
       </div>
     </div>
   );
 };
 
-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 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 +253,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 Loading = () => {
+  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>