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

package/src/components/button/ButtonGroup.tsx

@@ -71,6 +71,32 @@ export interface ButtonGroupProps
   fullWidth?: boolean;
 }
 
+/**
+ * A component that groups buttons together, allowing for consistent styling and behavior across multiple buttons.
+ * It supports vertical orientation, various button styles, and can handle properties like size, color, and disabled state.
+ * This component is useful for creating button groups that maintain a uniform appearance and functionality,
+ * such as toolbars, action groups, or navigation buttons.
+ *
+ * @param {ButtonGroupProps} props - The properties for the ButtonGroup component.
+ * @returns {JSX.Element} The rendered ButtonGroup component.
+ *
+ * @example
+ * ```jsx
+ * <ButtonGroup
+ *   variant="solid"
+ *   color="primary"
+ *   className="my-custom-class"
+ *   aria-label="Button Group"
+ *   vertical
+ * >
+ *   <Button>Button 1</Button>
+ *   <Button>Button 2</Button>
+ *   <Button>Button 3</Button>
+ * </ButtonGroup>
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/docs/core-components-buttongroup--docs} for more details.
+ */
 export const ButtonGroup = ({
   vertical,
   className,

package/src/components/button/ConfirmButton.tsx

@@ -80,7 +80,28 @@ interface ExtendedProps extends Omit<BaseProps, "onClick">, RefProp {
 export type ConfirmButtonProps = ExtendedProps & ButtonProps;
 
 /**
- * Button with confirmation dropdown
+ * A button that shows a confirmation dialog when clicked, allowing the user to confirm or cancel an action.
+ * It supports custom messages, labels, and loading states.
+ * This component is useful for actions that require user confirmation, such as deleting items or submitting forms.
+ * It uses the Floating UI library to manage the positioning of the confirmation dialog, ensuring it appears correctly relative to the button.
+ * It also supports custom placement of the dialog, and can display an action message when the action is completed.
+ *
+ * @param {ConfirmButtonProps} props - The properties for the ConfirmButton component.
+ * @returns {JSX.Element} The rendered ConfirmButton component.
+ *
+ * @example
+ * ```jsx
+ * <ConfirmButton
+ *   message="Are you sure you want to delete this item?"
+ *   onClick={(confirmed) => {
+ *     if (confirmed) {
+ *       // Perform action
+ *     }
+ *   }}
+ * />
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/docs/core-components-confirmbutton--docs} for more details.
  */
 export const ConfirmButton = <Tag extends React.ElementType = "button">({
   ref,

package/src/components/button/ToggleButtonGroup.tsx

@@ -23,7 +23,7 @@
 
 import { EMPTY_ARRAY, isArray } from "@react-fabric/utilities";
 import classNames from "classnames";
-import { cloneElement, useCallback, useMemo } from "react";
+import { cloneElement, useCallback } from "react";
 import { useControlledValue } from "../../hooks/useControlledValue";
 import {
   type AriaProps,
@@ -35,10 +35,7 @@ import {
 import { cloneChildren } from "../../utils";
 import { type ButtonProps } from "./Button";
 
-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],
@@ -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

@@ -63,6 +63,7 @@ export interface CalloutProps
   onClose?: () => void;
 }
 
+// colors for different callout types
 const colors = {
   none: "bg-base text-tint-900 border-tint-100",
   tint: "bg-tint-50/50 text-tint-800 border-tint-300",
@@ -74,6 +75,32 @@ const colors = {
   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

package/src/components/card/Card.tsx

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

package/src/components/card/CardCover.tsx

@@ -48,6 +48,31 @@ const scheme = {
   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,

package/src/components/card/FlipContent.tsx

@@ -39,6 +39,27 @@ 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);
 

package/src/components/chip/Chip.tsx

@@ -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,
@@ -170,7 +190,7 @@ export const Chip = <Tag extends React.ElementType = "div">({
       {icon && (
         <Icon
           data-ref="chipIcon"
-          className={classNames("fabric-chipIcon", "m-1")}
+          className={classNames("fabric-chipIcon", "m-1 flex-auto")}
           icon={icon}
           bg={iconBg}
           onClick={onIconClick}

package/src/components/collapsable/Collapsable.tsx

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

package/src/components/divider/Divider.tsx

@@ -54,6 +54,25 @@ export interface DividerProps extends CssProp, Partial<ChildProp> {
   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 = "tint-300",

package/src/components/dropdown/Dropdown.tsx

@@ -276,12 +276,52 @@ const DropdownElement = ({
   );
 };
 
+/**
+ * A component that displays a dropdown menu with an anchor and a panel.
+ * It supports various features such as placement, arrow display, click handling,
+ * and event handling for opening and closing the dropdown.
+ *
+ * @param props - Dropdown properties
+ * @returns JSX Element
+ *
+ * @example
+ * ```jsx
+ * <Dropdown
+ *   placement="bottom"
+ *   showArrow
+ *   closeOnClick
+ *   fitToParent
+ *   onOpen={() => console.log("Dropdown opened")}
+ *   onClose={() => console.log("Dropdown closed")}
+ * >
+ *   <button>Open Dropdown</button>
+ *   <div>
+ *     <DropdownDismiss>
+ *       <button>Dismiss</button>
+ *     </DropdownDismiss>
+ *     <p>Dropdown Content</p>
+ *   </div>
+ * </Dropdown>
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/docs/core-components-dropdown--docs} for more details.
+ * @see {@link https://floating-ui.com/docs/react} for more details on Floating UI.
+ */
 export const Dropdown = (props: DropdownProps) => (
   <FloatingTree>
     <DropdownElement {...props} />
   </FloatingTree>
 );
 
+/**
+ * A component that allows dismissing the dropdown when clicked.
+ * It can be used inside the dropdown panel to provide a dismiss area.
+ * It supports an optional `dismiss` prop to control whether the dropdown should be dismissed on click.
+ *
+ * @param children - The children elements to render inside the dismiss area.
+ * @param dismiss - Whether to dismiss the dropdown on click (default: true).
+ * @returns JSX Element
+ */
 export const DropdownDismiss = ({
   children,
   dismiss = true,

package/src/components/dropdown/DropdownTool.tsx

@@ -27,6 +27,31 @@ import { CoreIcons } from "../../types/icons";
 import { Icon } from "../icon/Icon";
 import { Dropdown, type DropdownProps } from "./Dropdown";
 
+/**
+ * A dropdown component that displays an icon and tool menu.
+ * It can be used to create a dropdown menu that appears when the icon is clicked or hovered over.
+ * This component is useful for creating toolbars or action menus in a user interface.
+ * It accepts children as menu items and can be styled with additional CSS classes.
+ *
+ * @param {ChildProp} children - The content to be displayed inside the dropdown.
+ * @param {CssProp} className - Additional CSS classes to apply to the dropdown.
+ * @param {string} icon - The icon to be displayed in the dropdown.
+ * @param {boolean} groupHover - If true, the dropdown will only be visible when the parent group is hovered.
+ * @param {DropdownProps} props - Additional properties for the dropdown.
+ * @returns {JSX.Element} The rendered DropdownTool component.
+ *
+ * @example
+ * ```jsx
+ * <DropdownTool
+ *   icon="caret-down"
+ *   groupHover={true}
+ *   className="my-dropdown"
+ * >
+ *   <MenuItem>Item 1</MenuItem>
+ *   <MenuItem>Item 2</MenuItem>
+ * </DropdownTool>
+ * ```
+ */
 export const DropdownTool = ({
   children,
   className,

package/src/components/empty/EmptyContent.tsx

@@ -105,6 +105,32 @@ const DefaultIcon = () => (
   </svg>
 );
 
+/**
+ * A component that displays a message and an optional icon when there is no content to show.
+ * It allows customization of title, message, icon, size, and additional CSS properties.
+ * It can also accept children elements for additional actions or information.
+ * This component is useful for displaying a friendly message when data is not available,
+ * such as in empty states of lists, tables, or other content areas.
+ *
+ * @param {EmptyContentProps} props - The properties for the EmptyContent component.
+ * @returns {JSX.Element} The rendered EmptyContent component.
+ *
+ * @example
+ * ```jsx
+ * <EmptyContent
+ *   title="No Data Available"
+ *   message="Please check back later."
+ *   icon="empty"
+ *   iconColor="tint-700"
+ *   size="md"
+ * >
+ *   <Button onClick={() => console.log("Action clicked")}>Retry</Button>
+ * </EmptyContent>
+ * // Renders an empty content area with a title, message, icon, and a button for retrying the action.
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/docs/core-components-emptycontent--docs} for more details.
+ */
 export const EmptyContent = ({
   children,
   title,

package/src/components/icon/Icon.tsx

@@ -85,7 +85,33 @@ const SizeMap: KeyValue<string> = {
 };
 
 /**
- * An icon is a display component for svg icon path / image
+ * A versatile icon component that supports SVG paths, webfont icons, and text icons.
+ * It can be styled with background color, icon color, size, and animations.
+ * It also supports RTL flipping and rounded corners.
+ * The component can be used as a standalone icon or as part of other components.
+ * It accepts various properties to customize its appearance and behavior.
+ * These include `bg`, `color`, `size`, `rtlFlip`, `animate`, and `rounded`.
+ *
+ * @param {IconProps} props - The properties for the Icon component.
+ * @returns {JSX.Element} The rendered Icon component.
+ *
+ * @example
+ * ```jsx
+ * <Icon
+ *   icon="M10 20v-6h4v6h5v-8h3L12 3 2 12h3v8z"
+ *   bg="bg-blue-500"
+ *   color="text-white"
+ *   size="lg"
+ *   rtlFlip={true}
+ *   animate="spin"
+ *   rounded={true}
+ *   onClick={() => console.log("Icon clicked")}
+ * />
+ * // Renders an icon with a SVG path, blue background, white text color,
+ * // large size, RTL flip, spin animation, rounded corners, and a click handler.
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/docs/core-components-icon--docs} for more details.
  */
 export const Icon = ({
   ref,