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

package/src/components/card/Card.tsx

@@ -24,9 +24,10 @@
 import classNames from "classnames";
 import {
   Children,
-  useMemo,
   type DragEvent,
   type MouseEventHandler,
+  useCallback,
+  useMemo,
 } from "react";
 import { ErrorBoundary } from "../../core/boundary/ErrorBoundary";
 import { type ContentProps } from "../../core/content/Content";
@@ -39,15 +40,16 @@ import {
   type AriaProps,
   type ChildrenProp,
   type CssProp,
+  type RefProp,
   type TestProps,
 } from "../../types";
 import { nodeCheck } from "../../utils";
-import classes from "./Card.module.css";
 
 export interface CardProps
   extends CssProp,
     AriaProps,
     TestProps,
+    RefProp<HTMLDivElement>,
     ChildrenProp<React.ReactElement<HeadFootProps | ContentProps>> {
   /**
    * apply flex fill styling
@@ -57,6 +59,14 @@ export interface CardProps
    * click handler
    */
   onClick?: MouseEventHandler;
+  /**
+   * drag start handler
+   */
+  onDragStart?: (
+    event: DragEvent,
+    dragKey: string,
+    dragData?: KeyValue,
+  ) => void;
   /**
    * body css classname(s)
    */
@@ -83,6 +93,40 @@ export interface CardProps
   dragData?: KeyValue;
 }
 
+/**
+ * A component that displays a card with a header, body, and footer. It can be used to display content in a structured format.
+ * It supports various features such as click handling, drag-and-drop functionality, and customizable styles.
+ * The Card component is designed to be flexible and can be used in various contexts, such as displaying user profiles, product information, or any other content that benefits from a card layout.
+ * The component accepts children that can include a Header, body content, and a Footer.
+ * It also supports additional properties for styling, accessibility, and interaction.
+ * It can be styled with custom CSS classes and supports features like selection indication and drag-and-drop functionality.
+ *
+ * @param {CardProps} props - The properties for the Card component.
+ * @returns {JSX.Element} The rendered Card component.
+ *
+ * @example
+ * ```jsx
+ * <Card
+ *   className="my-custom-class"
+ *   bodyClassName="my-body-class"
+ *   selected={true}
+ *   selectedRibbon={true}
+ *   onClick={() => console.log("Card clicked")}
+ *   onDragStart={(event, key, data) => console.log("Drag started", key, data)}
+ *   flex={true}
+ *   draggable={true}
+ *   dragKey="my-drag-key"
+ *   dragData={{ id: 1, name: "Card Data" }}
+ *   aria-label="My Card"
+ * >
+ *   <Header>Card Header</Header>
+ *   <div>Card Body Content</div>
+ *   <Footer>Card Footer</Footer>
+ * </Card>
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/docs/core-components-card--docs} for more details.
+ */
 export const Card = ({
   children,
   className,
@@ -90,10 +134,12 @@ export const Card = ({
   selected,
   selectedRibbon,
   onClick,
+  onDragStart,
   flex,
   draggable,
   dragKey,
   dragData,
+  ref,
   ...aria
 }: CardProps) => {
   const [header, body, footer] = useMemo(() => {
@@ -110,38 +156,41 @@ export const Card = ({
     );
   }, [children]);
 
+  const handleDragStart = useCallback(
+    (event: DragEvent) => {
+      dragKey && event.dataTransfer?.setData(dragKey, JSON.stringify(dragData));
+      dragKey && onDragStart?.(event, dragKey, dragData);
+    },
+    [onDragStart, dragKey, dragData],
+  );
+
   return (
     <div
       className={classNames(
-        classes.cardWrapper,
+        "fabric-cardWrapper",
         "rounded-capped relative grid",
         flex && "flex-1",
-        selected && selectedRibbon && classes.selected,
-        selected && "outline outline-2 outline-accent-500 outline-offset-2",
+        selected && selectedRibbon && "selected",
+        selected && "outline-2 outline-accent-500 outline-offset-2",
       )}
     >
       <ErrorBoundary>
         <div
           className={classNames(
-            classes.card,
+            "fabric-card",
             className,
             "rounded-capped flex flex-col flex-nowrap overflow-hidden",
-            onClick && classes.clickable,
+            onClick && "clickable",
           )}
           draggable={draggable}
-          onDragStart={
-            !draggable
-              ? undefined
-              : (e: DragEvent) =>
-                  dragKey &&
-                  e.dataTransfer?.setData(dragKey, JSON.stringify(dragData))
-          }
+          onDragStart={!draggable ? undefined : handleDragStart}
+          ref={ref}
           {...aria}
         >
           {header}
           <div
             role="none"
-            className={classNames(classes.cardBody, bodyClassName, "flex-1")}
+            className={classNames("fabric-cardBody", bodyClassName, "flex-1")}
             onClick={onClick}
           >
             {body}

package/src/components/card/CardCover.tsx

@@ -26,7 +26,6 @@ import { Children, useMemo } from "react";
 import { type AriaProps, type ChildrenProp, type CssProp } from "../../types";
 import { nodeCheck } from "../../utils";
 import { Image, Video } from "../media/Media";
-import classes from "./Card.module.css";
 
 export interface CardCoverProps extends CssProp, AriaProps, ChildrenProp {
   /**
@@ -43,12 +42,44 @@ export interface CardCoverProps extends CssProp, AriaProps, ChildrenProp {
   justify?: "start" | "center" | "end";
 }
 
+const scheme = {
+  inheritScheme: "inheritScheme",
+  light: "light",
+  dark: "dark",
+};
+
+/**
+ * A cover component for cards that can contain media and content.
+ * It allows for flexible layout options and supports different color schemes.
+ * It can be used to create visually appealing card layouts with media content.
+ *
+ * @param {CardCoverProps} props - The properties for the CardCover component.
+ * @returns {JSX.Element} The rendered CardCover component.
+ *
+ * @example
+ * ```jsx
+ * <CardCover
+ *   height={200}
+ *   colorScheme="light"
+ *   justify="center"
+ *   className="my-custom-class"
+ *   aria-label="Card Cover"
+ * >
+ *   <Image src="image.jpg" alt="Card Image" />
+ *   <div>Card Content</div>
+ * </CardCover>
+ * // Renders a card cover with a height of 200px, light color scheme, centered content, and a custom class name.
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/story/core-components-card--docs} for more details.
+ */
 export const CardCover = ({
   className,
   children,
   height = 120,
   justify = "end",
-  colorScheme,
+  // @ts-expect-error ignore
+  colorScheme = "inheritScheme",
   ...aria
 }: CardCoverProps) => {
   const [media, body] = useMemo(() => {
@@ -64,8 +95,8 @@ export const CardCover = ({
     <div
       style={{ height }}
       className={classNames(
-        classes.cardCover,
-        classes[colorScheme ?? "inheritScheme"],
+        "fabric-cardCover",
+        scheme[colorScheme],
         "relative z-0",
       )}
       {...aria}
@@ -73,9 +104,8 @@ export const CardCover = ({
       {media}
       <div
         className={classNames(
-          classes.cardCoverContent,
+          "fabric-cardCoverContent",
           "relative pointer-events-none z-1 flex flex-col flex-nowrap p-4 h-full",
-          className,
           `justify-${justify}`,
           className,
         )}

package/src/components/card/FlipContent.tsx

@@ -0,0 +1,90 @@
+/*
+ * React Fabric
+ * @version: 1.0.0
+ *
+ *
+ * The MIT License (MIT)
+ * Copyright (c) 2025 Adarsh Pastakia
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software
+ * and associated documentation files (the "Software"), to deal in the Software without restriction,
+ * including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ * and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all copies or substantial
+ * portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
+ * TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+ * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+ * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+import classNames from "classnames";
+import {
+  Children,
+  cloneElement,
+  isValidElement,
+  useImperativeHandle,
+  useState,
+} from "react";
+import { type ChildrenProp, type CssProp, type RefProp } from "../../types";
+
+export interface FlipContentRef {
+  flipCard: () => void;
+}
+
+export interface Props extends ChildrenProp, RefProp<FlipContentRef> {
+  //
+}
+
+/**
+ * A component that allows flipping between front and back content.
+ * It uses a ref to control the flipping action, which toggles the visibility of the front and back content.
+ * The component accepts children elements, which should be valid React elements representing the front and back content.
+ * The front content is expected to be the first child, and the back content is expected to be the second child.
+ * The component applies specific classes to the children based on their position (front or back) and manages the flipping state internally.
+ * The `flipCard` method can be called to toggle the visibility of the back content.
+ *
+ * @param {Props} props - The properties for the FlipContent component.
+ * @returns {JSX.Element} The rendered FlipContent component.
+ *
+ * @example
+ * ```jsx
+ * <FlipContent ref={flipRef}>
+ *   <div className="front">Front Content</div>
+ *   <div className="back">Back Content</div>
+ * </FlipContent>
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/docs/core-components-flipcontent--docs}
+ */
+export const FlipContent = ({ ref, children }: Props) => {
+  const [showBack, setShowBack] = useState(false);
+
+  useImperativeHandle(
+    ref,
+    () => ({
+      flipCard: () => setShowBack(!showBack),
+    }),
+    [showBack],
+  );
+
+  return (
+    <div className="relative flex-1" data-card-flip={showBack}>
+      {Children.map(
+        children,
+        (child, idx) =>
+          isValidElement<CssProp>(child) &&
+          cloneElement(child, {
+            className: classNames(
+              child.props?.className ?? "",
+              idx === 0 ? "bg-base relative" : "bg-base absolute inset-0",
+            ),
+            "data-card-flip-face": idx === 0 ? "front" : "back",
+          } as AnyObject),
+      )}
+    </div>
+  );
+};

package/src/components/chip/Chip.tsx

@@ -30,14 +30,14 @@ import {
   type ColorType,
   type CssProp,
   type IconProps,
+  type PaletteType,
   type PolymorphicProps,
   type RefProp,
   type SizeType,
   type TestProps,
 } from "../../types";
-import { getColor, getColorClass } from "../../utils";
+import { getColor } from "../../utils";
 import { Icon } from "../icon/Icon";
-import classes from "./Chip.module.css";
 
 export interface ChipProps
   extends CssProp,
@@ -49,11 +49,11 @@ export interface ChipProps
   /**
    * chip size
    */
-  size?: SizeType;
+  size?: SizeType | number | string;
   /**
    * chip color (CSS color / tailwind color)
    */
-  color?: ColorType | string;
+  color?: ColorType | PaletteType | string;
   /**
    * chip styling
    */
@@ -92,6 +92,26 @@ const SizeMap: KeyValue<string> = {
   xl: "2rem",
 };
 
+/**
+ * A component that represents a small block of information, often used for tags, categories, or actions.
+ * It allows customization of size, color, variant, and includes optional icon and remove functionality.
+ * It supports various properties for styling and interaction, including click handlers and disabled state.
+ * It can be used in various contexts, such as filtering options, displaying tags, or representing user actions.
+ * It can be styled with custom CSS classes and supports features like rounded edges and click handling.
+ * It can also include an icon and a remove button, making it versatile for different use cases.
+ *
+ * @param {ChipProps} props - The properties for the Chip component.
+ * @returns {JSX.Element} The rendered Chip component.
+ *
+ * @example
+ * ```jsx
+ * <Chip color="primary" size="md" className="my-chip">
+ *   Example Chip
+ * </Chip>
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/docs/core-components-chip--docs} for more details.
+ */
 export const Chip = <Tag extends React.ElementType = "div">({
   ref,
   children,
@@ -152,24 +172,25 @@ export const Chip = <Tag extends React.ElementType = "div">({
     <E
       ref={ref}
       role="term"
+      data-ref="chip"
       className={classNames(
-        classes.chip,
+        "fabric-chip",
         className,
-        color && getColorClass(color),
-        "select-none inline-flex flex-nowrap items-center max-w-72 text-sm rounded",
+        "select-none inline-flex flex-nowrap items-center align-middle max-w-72 rounded",
         rounded && "rounded-full",
-        !!onClick && classes.clickable,
-        disabled && classes.disabled,
+        !!onClick && "clickable",
+        disabled && "disabled",
       )}
       style={styles}
       data-variant={variant}
       data-inner-clickable={!!onClick}
-      {...{ onClick: clickHandler }}
+      {...{ onClick: disabled ? undefined : clickHandler }}
       {...aria}
     >
       {icon && (
         <Icon
-          className={classNames(classes.chipIcon, "m-1")}
+          data-ref="chipIcon"
+          className={classNames("fabric-chipIcon", "m-1 flex-auto")}
           icon={icon}
           bg={iconBg}
           onClick={onIconClick}
@@ -178,15 +199,20 @@ export const Chip = <Tag extends React.ElementType = "div">({
         />
       )}
       {children && (
-        <label className={classNames(classes.chipLabel, "truncate")}>
+        <label
+          data-ref="chipLabel"
+          className={classNames("fabric-chipLabel", "truncate")}
+        >
           {children}
         </label>
       )}
       {onRemove && (
         <span
           role="none"
+          data-ref="chipRemove"
+          data-inner-cliackable
           className={classNames(
-            classes.chipRemove,
+            "fabric-chipRemove",
             "cursor-pointer pe-1 opacity-65 hover:opacity-90",
           )}
           onClick={removeHandler}

package/src/components/collapsable/Collapsable.tsx

@@ -40,11 +40,10 @@ import {
 } from "../../types";
 import { CoreIcons } from "../../types/icons";
 import { Icon } from "../icon/Icon";
-import classes from "./Collapsable.module.css";
 
 interface CollapsableRef {
-  button: RefObject<HTMLElement>;
-  body: RefObject<HTMLElement>;
+  button: RefObject<HTMLElement | null>;
+  body: RefObject<HTMLElement | null>;
   open: boolean;
 }
 
@@ -66,6 +65,10 @@ export interface CollapsableProps
    * header button className
    */
   headerClassName?: string;
+  /**
+   * Header position sticky
+   */
+  stickyHeader?: boolean;
   /**
    * open state icon
    */
@@ -92,6 +95,32 @@ export interface CollapsableProps
   onClose?: () => void;
 }
 
+/**
+ * A component that can be expanded or collapsed to show or hide content.
+ * It is useful for organizing content in a way that allows users to focus on the information they are interested in.
+ * It supports custom icons for open and closed states, alignment options, and can be made sticky.
+ * This component is ideal for creating accordions, expandable panels, or sections that can be toggled by the user.
+ *
+ * @param {CollapsableProps} props - The properties for the Collapsable component.
+ * @returns {JSX.Element} The rendered Collapsable component.
+ *
+ * @example
+ * ```jsx
+ * <Collapsable
+ *   iconAlign="start"
+ *   iconOpen={CoreIcons.chevronDown}
+ *   iconClosed={CoreIcons.chevronRight}
+ *   open={true}
+ *   onOpen={() => console.log("Opened")}
+ *   onClose={() => console.log("Closed")}
+ * >
+ *   <div>Header Content</div>
+ *   <div>Body Content</div>
+ * </Collapsable>
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/docs/core-components-collapsable--docs} for more details.
+ */
 export const Collapsable = ({
   ref,
   disabled,
@@ -100,6 +129,7 @@ export const Collapsable = ({
   headerClassName,
   children,
   iconAlign,
+  stickyHeader,
   iconClosed = CoreIcons.chevronRight,
   iconOpen = CoreIcons.chevronDown,
   open,
@@ -130,25 +160,26 @@ export const Collapsable = ({
     return [h, b];
   }, [children]);
   return (
-    <div className={classNames(classes.collapsable, className)} {...aria}>
+    <div className={classNames("fabric-collapsable", className)} {...aria}>
       <div
         role="none"
         ref={headRef}
         className={classNames(
-          classes.collapsableHead,
+          "fabric-collapsableHead",
           "flex gap-1 flex-nowrap py-2 font-medium cursor-pointer items-center select-none hover:opacity-70",
           headerClassName,
+          stickyHeader && "bg-base sticky top-0 py-1 z-10",
           iconAlign === "end" ? "flex-row-reverse" : "flex-row",
         )}
         onClick={() => !disabled && setOpenState(!openState)}
       >
         <Icon size="1.125em" icon={openState ? iconOpen : iconClosed} rtlFlip />
-        <div className="flex-1 px-2">{head}</div>
+        <div className="flex-1">{head}</div>
       </div>
       {openState && (
         <div
           ref={bodyRef}
-          className={classNames(classes.collapsableBody, bodyClassName)}
+          className={classNames("fabric-collapsableBody", bodyClassName)}
         >
           {body}
         </div>

package/src/components/divider/Divider.tsx

@@ -24,37 +24,61 @@
 import classNames from "classnames";
 import { useCallback } from "react";
 import {
-  type CssProp,
   type ChildProp,
   type ColorType,
+  type CssProp,
   type PaletteType,
 } from "../../types";
-import { getBgClass, getBorderClass, getColorClass } from "../../utils";
+import { getColor } from "../../utils";
 
 export interface DividerProps extends CssProp, Partial<ChildProp> {
-  /**
-   * apply text bg
-   */
-  fill?: boolean;
   /**
    * vertical rule
    */
   vertical?: boolean;
+  /**
+   * divider label classname(s)
+   */
+  labelClassName?: string;
   /**
    * rule color
    */
-  color?: ColorType | PaletteType | "tint";
+  color?: ColorType | PaletteType | string;
   /**
    * text alignment
    */
   align?: "start" | "end" | "center";
+  /**
+   * divider style
+   */
+  style?: "solid" | "dashed" | "dotted";
 }
 
+/**
+ * A component that represents a visual divider between content.
+ * It can be used to separate sections of content, with optional text labels.
+ * It supports both horizontal and vertical orientations, customizable colors,
+ * styles, and alignment options.
+ *
+ * @param {DividerProps} props - The properties for the Divider component.
+ * @returns {JSX.Element} The rendered Divider component.
+ *
+ * @example
+ * ```jsx
+ * <Divider color="primary" align="center" style="dashed">
+ *   Divider Text
+ * </Divider>
+ * // Renders a horizontal divider with primary color, centered text, and dashed style.
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/docs/core-components-divider--docs} for more details.
+ */
 export const Divider = ({
   children,
-  color,
+  color = "tint-300",
   vertical,
-  fill,
+  labelClassName,
+  style,
   align = "start",
   className,
 }: DividerProps) => {
@@ -62,13 +86,14 @@ export const Divider = ({
     ({ flex, className }: KeyValue) => {
       return (
         <hr
-          style={{ flex }}
+          style={{ flex, borderColor: getColor(color), borderStyle: style }}
           className={classNames(
             className,
             vertical && "vertical",
             !flex && "self-stretch",
-            vertical ? "mx-1" : "my-1",
-            color && getBorderClass(color + "-200"),
+            vertical
+              ? "fabric-divider--vertical"
+              : "fabric-divider--horizontal",
           )}
         />
       );
@@ -79,7 +104,7 @@ export const Divider = ({
   return children ? (
     <div
       className={classNames(
-        "flex flex-nowrap items-center",
+        "flex flex-nowrap items-center fabric-divider",
         vertical && "flex-col",
         className,
       )}
@@ -88,9 +113,10 @@ export const Divider = ({
       <div
         className={classNames(
           "px-2 whitespace-nowrap",
-          vertical ? "mx-1" : "my-1",
-          fill && getBgClass((color ?? "tint") + "-200"),
-          !fill && getColorClass((color ?? "tint") + "-600"),
+          vertical
+            ? "fabric-divider-label--vertical"
+            : "fabric-divider-label--horizontal",
+          labelClassName,
           "rounded-full text-[0.75em]",
           vertical && "origin-center -rotate-90 z-1",
         )}