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

package/src/components/button/ToggleButtonGroup.tsx

@@ -23,7 +23,7 @@
 
 import { EMPTY_ARRAY, isArray } from "@react-fabric/utilities";
 import classNames from "classnames";
-import { Children, cloneElement, useCallback, useMemo } from "react";
+import { cloneElement, useCallback } from "react";
 import { useControlledValue } from "../../hooks/useControlledValue";
 import {
   type AriaProps,
@@ -32,13 +32,10 @@ import {
   type CssProp,
   type SizeType,
 } from "../../types";
+import { cloneChildren } from "../../utils";
 import { type ButtonProps } from "./Button";
-import classes from "./Button.module.css";
 
-interface BaseProps
-  extends CssProp,
-    AriaProps,
-    ChildrenProp<React.ReactElement<ButtonProps & { value: string }>> {
+interface BaseProps extends CssProp, AriaProps {
   /**
    * vertical orientation
    */
@@ -69,31 +66,61 @@ interface BaseProps
   fullWidth?: boolean;
 }
 
-export type ToggleButtonGroupProps = BaseProps &
-  (
-    | {
-        /**
-         *
-         */
-        value: string;
-        /**
-         * change handler
-         */
-        onChange?: (value: string) => void;
-      }
-    | {
-        /**
-         *
-         */
-        value: string[];
-        /**
-         * change handler
-         */
-        onChange?: (value: string[]) => void;
-      }
-  );
+export type ToggleButtonGroupValueProps<T> =
+  | {
+      /**
+       *
+       */
+      value: T;
+      /**
+       * change handler
+       */
+      onChange?: (value: T | null) => void;
+    }
+  | {
+      /**
+       *
+       */
+      value: T[];
+      /**
+       * change handler
+       */
+      onChange?: (value: T[] | null) => void;
+    };
+
+export type ToggleButtonGroupProps<T> = BaseProps &
+  ChildrenProp<React.ReactElement<ButtonProps & { value: T }>> &
+  ToggleButtonGroupValueProps<T>;
 
-export const ToggleButtonGroup = ({
+/**
+ * A component that groups toggle buttons together, allowing for consistent styling and behavior across multiple toggle buttons.
+ * It supports vertical orientation, various button styles, and can handle properties like size, color, and disabled state.
+ * This component is useful for creating toggle button groups that maintain a uniform appearance and functionality,
+ * such as toggle switches, selection groups, or multi-select options.
+ *
+ * @param {ToggleButtonGroupProps} props - The properties for the ToggleButtonGroup component.
+ * @returns {JSX.Element} The rendered ToggleButtonGroup component.
+ *
+ * @example
+ * ```jsx
+ * <ToggleButtonGroup
+ *   value={selectedValues}
+ *   onChange={(newValues) => setSelectedValues(newValues)}
+ *   variant="outline"
+ *   color="primary"
+ *   size="md"
+ *   rounded
+ *   fullWidth
+ * >
+ *   <Button value="option1">Option 1</Button>
+ *   <Button value="option2">Option 2</Button>
+ *   <Button value="option3">Option 3</Button>
+ * </ToggleButtonGroup>
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/docs/core-components-togglebuttongroup--docs} for more details.
+ */
+export const ToggleButtonGroup = <T extends AnyObject = string>({
   vertical,
   className,
   children,
@@ -106,23 +133,24 @@ export const ToggleButtonGroup = ({
   value,
   onChange,
   ...aria
-}: ToggleButtonGroupProps) => {
-  const isMultiple = useMemo(() => isArray(value), [value]);
-  const { currentValue, updateValue } = useControlledValue<typeof value>(
+}: ToggleButtonGroupProps<T>) => {
+  const { currentValue, updateValue } = useControlledValue(
     value,
-    isArray(value) ? EMPTY_ARRAY : "",
+    isArray(value) ? EMPTY_ARRAY : null,
   );
 
   const clickHandler = useCallback(
-    (cb: AnyObject) => (e: React.MouseEvent<HTMLElement>) => {
-      let newValue: AnyObject = `${e.currentTarget.dataset.value}`;
+    (cb: AnyObject, childValue: T) => (e: React.MouseEvent<HTMLElement>) => {
+      let newValue;
       if (isArray(currentValue)) {
-        if (currentValue.includes(newValue))
-          newValue = currentValue.filter((v) => v !== newValue);
-        else newValue = [...currentValue, newValue];
+        if (currentValue.includes(childValue))
+          newValue = currentValue.filter((v) => v !== childValue);
+        else newValue = [...currentValue, childValue];
+      } else {
+        newValue = childValue;
       }
       updateValue(newValue);
-      onChange?.(newValue);
+      onChange?.(newValue as AnyObject);
       cb?.(e);
     },
     [currentValue, onChange],
@@ -131,16 +159,16 @@ export const ToggleButtonGroup = ({
   return (
     <div
       className={classNames(
-        classes.buttonGroup,
+        "fabric-buttonGroup",
         className,
         fullWidth ? "flex" : "inline-flex",
         "flex-nowrap align-middle",
-        vertical && classes.vertical,
+        vertical && "vertical",
         vertical && "flex-col",
       )}
       {...aria}
     >
-      {Children.map(children, (child: AnyObject) =>
+      {cloneChildren(children, (child: AnyObject) =>
         cloneElement(child, {
           color,
           size,
@@ -149,10 +177,9 @@ export const ToggleButtonGroup = ({
           rounded,
           fullWidth,
           ...child.props,
-          onClick: clickHandler(child.props.onClick),
-          "data-value": child.props.value,
-          "data-checked": isMultiple
-            ? currentValue.includes(child.props.value)
+          onClick: clickHandler(child.props.onClick, child.props.value),
+          "data-checked": isArray(currentValue)
+            ? currentValue?.includes(child.props.value)
             : currentValue === child.props.value,
         }),
       )}

package/src/components/callout/Callout.tsx

@@ -25,13 +25,10 @@ import classNames from "classnames";
 import {
   type AriaProps,
   type ChildrenProp,
-  type ColorType,
+  type ColorState,
   type CssProp,
-  type PaletteType,
   type TestProps,
 } from "../../types";
-import { CoreIcons } from "../../types/icons";
-import { getBgClass, getBorderClass, getColorClass } from "../../utils";
 import { Icon } from "../icon/Icon";
 
 export interface CalloutProps
@@ -42,11 +39,11 @@ export interface CalloutProps
   /**
    * callout color
    */
-  color?: ColorType | PaletteType;
+  color?: ColorState | "none";
   /**
    * legend title
    */
-  legend?: string;
+  legend?: string | React.ReactElement;
   /**
    * callout icon
    */
@@ -65,10 +62,48 @@ export interface CalloutProps
   onClose?: () => void;
 }
 
+// colors for different callout types
+const colors = {
+  none: "bg-base text-tint-900 border-tint-100",
+  default: "bg-tint-50/50 text-tint-800 border-tint-300",
+  muted: "bg-tint-50/50 text-muted border-muted",
+  primary: "bg-primary-50/50 text-primary-800 border-primary-300",
+  accent: "bg-accent-50/50 text-accent-800 border-accent-300",
+  info: "bg-info-50/50 text-info-800 border-info-300",
+  danger: "bg-danger-50/50 text-danger-800 border-danger-300",
+  success: "bg-success-50/50 text-success-800 border-success-300",
+  warning: "bg-warning-50/50 text-warning-800 border-warning-300",
+};
+
+/**
+ * A component that displays a callout box with an optional title, icon, and legend.
+ * It can be used to highlight important information, warnings, or notices.
+ * The callout can be styled with different colors and border styles, and it supports a close action.
+ * This component is useful for drawing attention to specific content within a page or application,
+ * such as alerts, notifications, or important messages.
+ *
+ * @param {CalloutProps} props - The properties for the Callout component.
+ * @returns {JSX.Element} The rendered Callout component.
+ *
+ * @example
+ * ```jsx
+ * <Callout
+ *   color="primary"
+ *   legend="Important Notice"
+ *   title="Attention Required"
+ *   icon="info"
+ *   onClose={() => console.log("Callout closed")}
+ * >
+ *   This is an important message that requires your attention.
+ * </Callout>
+ * // Renders a callout box with a primary color, an icon, a title, and a close button.
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/story/core-components-callout--docs} for more details.
+ */
 export const Callout = ({
   children,
-  // @ts-expect-error ignore
-  color = "tint",
+  color = "default",
   legend,
   title,
   icon,
@@ -80,29 +115,36 @@ export const Callout = ({
   return (
     <fieldset
       className={classNames(
-        className,
         "block rounded-capped border max-w-full relative overflow-hidden mb-4",
-        getBgClass(color + "-50"),
-        getColorClass(color + "-700"),
-        getBorderClass(color + "-300"),
+        colors[color],
+        className,
         border === "dashed" && "border-dashed",
         border === "dotted" && "border-dotted",
       )}
       {...aria}
     >
-      {legend && <legend className="px-2 mx-4 font-medium">{legend}</legend>}
+      {legend && (
+        <legend className="px-2 mx-4 font-medium" data-ref="calloutLegend">
+          {legend}
+        </legend>
+      )}
       <div className={classNames("break-words whitespace-break-spaces p-2")}>
         <div className="flex flex-nowrap items-center text-xl pe-4 gap-2 mb-4 empty:mb-0">
-          {icon && <Icon icon={icon} />}
-          {title && <p className="flex-1">{title}</p>}
+          {icon && <Icon icon={icon} data-ref="calloutIcon" />}
+          {title && (
+            <p className="flex-1" data-ref="calloutTitle">
+              {title}
+            </p>
+          )}
         </div>
         <div className="pe-4">{children}</div>
       </div>
       {onClose && (
         <Icon
           size="md"
+          data-ref="calloutClose"
           className={classNames("absolute end-2", legend ? "top-0" : "top-2")}
-          icon={CoreIcons.close}
+          icon="icon-[mdi--close]"
           onClick={onClose}
         />
       )}

package/src/components/card/Card.tsx

@@ -24,6 +24,7 @@
 import classNames from "classnames";
 import {
   Children,
+  useCallback,
   useMemo,
   type DragEvent,
   type MouseEventHandler,
@@ -36,6 +37,7 @@ import {
   type HeadFootProps,
 } from "../../core/headfoot/HeadFoot";
 import {
+  type PolymorphicProps,
   type AriaProps,
   type ChildrenProp,
   type CssProp,
@@ -43,9 +45,8 @@ import {
   type TestProps,
 } from "../../types";
 import { nodeCheck } from "../../utils";
-import classes from "./Card.module.css";
 
-export interface CardProps
+interface BaseProps
   extends CssProp,
     AriaProps,
     TestProps,
@@ -59,6 +60,14 @@ export interface CardProps
    * click handler
    */
   onClick?: MouseEventHandler;
+  /**
+   * drag start handler
+   */
+  onDragStart?: (
+    event: DragEvent,
+    dragKey: string,
+    dragData?: KeyValue,
+  ) => void;
   /**
    * body css classname(s)
    */
@@ -85,20 +94,59 @@ export interface CardProps
   dragData?: KeyValue;
 }
 
-export const Card = ({
+export type CardProps<Tag extends React.ElementType = "div"> = BaseProps &
+  PolymorphicProps<Tag>;
+
+/**
+ * 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 = <Tag extends React.ElementType = "div">({
   children,
   className,
   bodyClassName,
   selected,
   selectedRibbon,
   onClick,
+  onDragStart,
   flex,
   draggable,
   dragKey,
   dragData,
   ref,
+  as,
   ...aria
-}: CardProps) => {
+}: CardProps<Tag>) => {
   const [header, body, footer] = useMemo(() => {
     return Children.toArray(children as AnyObject).reduce<AnyObject[]>(
       (ret, node) => {
@@ -113,43 +161,54 @@ 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],
+  );
+
+  const E = as ?? "div";
   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-1 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,
+            "rounded-capped relative flex flex-col flex-nowrap overflow-hidden",
+            "href" in aria && "clickable",
+            "to" in aria && "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")}
-            onClick={onClick}
-          >
-            {body}
-          </div>
+          <E role="none" onClick={onClick} {...aria} className="contents">
+            {body && (
+              <object
+                type="none"
+                className={classNames(
+                  "fabric-cardBody",
+                  bodyClassName,
+                  "flex-1",
+                )}
+              >
+                {body}
+              </object>
+            )}
+          </E>
           {footer}
         </div>
       </ErrorBoundary>

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>
+  );
+};