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

package/src/components/menu/MenuItem.tsx

@@ -22,17 +22,38 @@
  */
 
 import { useFloatingTree } from "@floating-ui/react";
-import { iconToken } from "@react-fabric/utilities";
+import { iconToken, mergeRefs } from "@react-fabric/utilities";
 import classNames from "classnames";
-import { Fragment, useCallback, useMemo } from "react";
+import { Fragment, useCallback, useEffect, useMemo, useRef } from "react";
+import { HotKey } from "../../hotkeys/HotKey";
 import { HotKeyLabel } from "../../hotkeys/HotKeyLabel";
 import { Tooltip } from "../../overlays";
 import { type PolymorphicProps } from "../../types";
 import { Badge, getBadgeProps } from "../badge/Badge";
 import { Icon } from "../icon/Icon";
-import classes from "./Menu.module.css";
 import { type MenuItemProps } from "./types";
 
+/**
+ * A menu item component that can be used in a dropdown or menu.
+ * It supports various features such as icons, badges, hotkeys, and more.
+ * It can be customized with different colors, icons, and behaviors.
+ *
+ * @param {MenuItemProps} props
+ * @returns A JSX element representing the menu item.
+ *
+ * @example
+ * ```jsx
+ * <MenuItem
+ *   label="Settings"
+ *   icon="settings"
+ *   onClick={() => console.log("Settings clicked")}
+ *   hotKey="Ctrl+S"
+ *   badge={{ count: 3, color: "red" }}
+ * />
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/docs/core-components-menu--docs} for documentation.
+ */
 export const MenuItem = <Tag extends React.ElementType = "button">({
   as,
   label,
@@ -50,6 +71,7 @@ export const MenuItem = <Tag extends React.ElementType = "button">({
   onClick,
   badge,
   hotKey,
+  tabIndex = -1,
   // @ts-expect-error ignore
   minimal,
   // @ts-expect-error ignore
@@ -58,11 +80,16 @@ export const MenuItem = <Tag extends React.ElementType = "button">({
   ref,
   ...aria
 }: MenuItemProps & PolymorphicProps<Tag>) => {
+  const elRef = useRef<HTMLElement>(null);
   const tree = useFloatingTree();
   const badgeProps = useMemo(() => {
     return getBadgeProps(badge);
   }, [badge]);
 
+  useEffect(() => {
+    tabIndex === 0 && elRef.current?.focus();
+  }, [tabIndex]);
+
   const iconEl = useMemo(() => {
     let path = icon;
     if (minimal && !path) {
@@ -70,7 +97,7 @@ export const MenuItem = <Tag extends React.ElementType = "button">({
     }
     return (
       <Icon
-        className={classNames(classes.menuIcon, minimal && classes.minimal)}
+        className={classNames("fabric-menuIcon", minimal && "minimal")}
         icon={path ?? ""}
         bg={iconBg}
         color={iconColor}
@@ -135,26 +162,30 @@ export const MenuItem = <Tag extends React.ElementType = "button">({
   return (
     <Wrapper {...aria}>
       <E
-        ref={ref}
+        ref={mergeRefs(ref, elRef)}
         data-dropdown-dismiss
         data-color={color}
         className={classNames(
-          classes.menuItem,
+          "fabric-menuItem cursor-pointer",
           className,
-          active && classes.active,
-          minimal && classes.minimal,
-          disabled && classes.disabled,
+          active && "active",
+          minimal && "minimal",
+          disabled && "disabled",
           "rounded-capped relative max-w-[50vw] my-0.5",
         )}
         data-active={active}
         data-open={childOpen}
         disabled={disabled}
         data-id={id}
+        tabIndex={tabIndex}
         onClick={(e) => {
           onClick?.(e) !== false && tree?.events.emit("click");
         }}
         {...(minimal ? {} : aria)}
       >
+        {hotKey && (
+          <HotKey keyCombo={hotKey} handler={() => elRef.current?.click?.()} />
+        )}
         {menuLabel}
       </E>
     </Wrapper>

package/src/components/menu/types.ts

@@ -27,7 +27,7 @@ import {
   type BadgeType,
   type CallbackReturn,
   type ChildrenProp,
-  type ColorType,
+  type ColorState,
   type CssProp,
   type IconProps,
   type TestProps,
@@ -53,7 +53,7 @@ export interface MenuItemProps
   /**
    * menu color
    */
-  color?: ColorType;
+  color?: ColorState;
   /**
    * item active
    */
@@ -90,6 +90,7 @@ export interface MenuRootProps extends CssProp {
 export interface MenuInnerProps extends MenuItemProps {
   label: string;
   minimal?: never;
+  trigger?: "hover" | "click";
   /**
    * floating menu className
    */

package/src/components/meter/Meter.tsx

@@ -25,7 +25,6 @@ import { Format } from "@react-fabric/utilities";
 import classNames from "classnames";
 import { useMemoDebugger } from "../../hooks/useEffectDebugger";
 import { type AriaProps, type CssProp, type TestProps } from "../../types";
-import classes from "./Meter.module.css";
 
 export interface MeterProps extends CssProp, AriaProps, TestProps {
   /**
@@ -38,6 +37,30 @@ export interface MeterProps extends CssProp, AriaProps, TestProps {
   hideLabel?: boolean;
 }
 
+/**
+ * A component that displays a visual representation of a value as a series of dots.
+ * It is useful for showing progress or completion status in a compact form.
+ * The meter consists of 6 dots, each representing approximately 16.67% of the total value.
+ * The active dots are filled based on the value provided, and the remaining dots are empty.
+ * The component can also display a label showing the percentage value.
+ *
+ * @param {MeterProps} props - The properties for the Meter component.
+ * @returns {JSX.Element} The rendered Meter component.
+ *
+ * @example
+ * ```jsx
+ * <Meter value={75} />
+ * // Renders a meter with 4 active dots and a label showing "75%"
+ *
+ * <Meter value={50} hideLabel />
+ * // Renders a meter with 3 active dots and no label
+ *
+ * <Meter value={100} className="custom-meter" />
+ * // Renders a meter with all 6 active dots and a custom class name
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/docs/core-components-meter--docs} for more details.
+ */
 export const Meter = ({ value, hideLabel, className, ...aria }: MeterProps) => {
   /** ***************** calculate active meter dots *******************/
   const activeCount = useMemoDebugger(
@@ -51,7 +74,7 @@ export const Meter = ({ value, hideLabel, className, ...aria }: MeterProps) => {
   return (
     <div
       className={classNames(
-        classes.meter,
+        "fabric-meter",
         className,
         "flex flex-nowrap items-center gap-[2px]",
       )}
@@ -61,7 +84,7 @@ export const Meter = ({ value, hideLabel, className, ...aria }: MeterProps) => {
         <div
           key={step}
           className={classNames(
-            classes.meterBar,
+            "fabric-meterBar",
             "first-of-type:rounded-s last-of-type:rounded-e bg-tint-100 relative outline -outline-offset-1 outline-muted overflow-hidden after:absolute after:inset-0",
           )}
           data-active={activeCount >= step}

package/src/components/navigator/Navigator.tsx

@@ -22,55 +22,106 @@
  */
 
 import classNames from "classnames";
+import { useCallback } from "react";
 import { HotKey } from "../../hotkeys/HotKey";
 import {
   type AriaProps,
+  type ChildProp,
   type ColorType,
   type CssProp,
+  type PaletteType,
   type TestProps,
 } from "../../types";
 import { CoreIcons } from "../../types/icons";
 import { Icon } from "../icon/Icon";
+import { isEmpty } from "@react-fabric/utilities";
 
-export interface NavigatorProps extends CssProp, AriaProps, TestProps {
+export interface NavigatorProps
+  extends CssProp,
+    AriaProps,
+    TestProps,
+    Partial<ChildProp> {
+  length?: number;
+  current?: number;
+  disableKeyHandlers?: boolean;
   /**
    * navigator button color
    */
-  color?: ColorType | string;
+  color?: ColorType | PaletteType | string;
   /**
    * navigation handler
    */
   onNavigate: (dir: -1 | 1) => void;
 }
 
+/**
+ * A component that provides navigation controls for traversing through items.
+ * It includes previous and next buttons, and supports keyboard navigation.
+ *
+ * @param {NavigatorProps} props - The properties for the Navigator component.
+ * @returns {JSX.Element} The rendered Navigator component.
+ *
+ * @example
+ * ```jsx
+ * <Navigator
+ *   className="my-navigator"
+ *   onNavigate={(dir) => console.log(`Navigate ${dir === -1 ? 'previous' : 'next'}`)}
+ *   color="blue"
+ *   length={10}
+ *   current={0}
+ * >
+ *   <span>Current Item: 1</span>
+ * </Navigator>
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/docs/core-components-navigator--docs} for more details.
+ */
 export const Navigator = ({
   className,
   onNavigate,
   color,
+  children,
+  length,
+  current,
+  disableKeyHandlers,
   ...aria
 }: NavigatorProps) => {
+  const navPrev = useCallback(
+    () => (isEmpty(current) || current !== 0) && onNavigate(-1),
+    [onNavigate, current],
+  );
+  const navNext = useCallback(
+    () => (isEmpty(current) || current + 1 < (length ?? 0)) && onNavigate(+1),
+    [onNavigate, current, length],
+  );
   return (
     <div
-      className={classNames(className, "inline-block leading-none")}
+      data-ref="navigator"
+      className={classNames(className, "inline-flex items-center leading-none")}
       {...aria}
     >
-      <HotKey keyCombo="left" handler={() => onNavigate(-1)} />
-      <HotKey keyCombo="right" handler={() => onNavigate(1)} />
+      {!disableKeyHandlers && <HotKey keyCombo="left" handler={navPrev} />}
+      {!disableKeyHandlers && <HotKey keyCombo="right" handler={navNext} />}
       <Icon
         rtlFlip
         color={color}
         className="text-[1em] p-1"
         aria-label="previous"
+        data-ref="previous"
         icon={CoreIcons.chevronLeft}
-        onClick={(e) => [e.stopPropagation(), onNavigate(-1)]}
+        disabled={!isEmpty(current) && current === 0}
+        onClick={(e) => [e.stopPropagation(), navPrev()]}
       />
+      {children}
       <Icon
         rtlFlip
         className="text-[1em] p-1"
         color={color}
         aria-label="next"
+        data-ref="next"
         icon={CoreIcons.chevronRight}
-        onClick={(e) => [e.stopPropagation(), onNavigate(1)]}
+        disabled={!isEmpty(current) && current + 1 === length}
+        onClick={(e) => [e.stopPropagation(), navNext()]}
       />
     </div>
   );

package/src/components/panel/Panel.tsx

@@ -38,7 +38,6 @@ import {
 import { CoreIcons } from "../../types/icons";
 import { Loading } from "../animations/Animations";
 import { Icon } from "../icon/Icon";
-import classes from "./Panel.module.css";
 
 export interface PanelProps
   extends CssProp,
@@ -102,6 +101,43 @@ export interface PanelProps
   onClose?: () => void;
 }
 
+/**
+ * A component that represents a panel with a header, body, and optional actions.
+ * It supports expandable and collapsible functionality, loading state, and customizable styles.
+ * The panel can be resized and has a fixed position when expanded.
+ * It can be customized with different colors, icons, and behaviors.
+ * This component is useful for displaying content in a structured way, allowing users to interact with it through actions and toggles.
+ * It can be used in various applications where panels are needed, such as dashboards, settings pages, or content management systems.
+ *
+ * @param {PanelProps} props - The properties for the Panel component.
+ * @returns {JSX.Element} The rendered Panel component.
+ *
+ * @example
+ * ```jsx
+ * <Panel
+ *   title="Panel Title"
+ *   icon={CoreIcons.info}
+ *   iconBg="bg-blue-500"
+ *   iconColor="text-white"
+ *   actions={<button>Action</button>}
+ *   expandable
+ *   collapsable
+ *   onExpand={() => console.log("Expanded")}
+ *   onCollapse={() => console.log("Collapsed")}
+ *   onClose={() => console.log("Closed")}
+ *   height="400px"
+ *   width="300px"
+ *   minHeight="200px"
+ *   minWidth="200px"
+ *   maxHeight="600px"
+ *   maxWidth="600px"
+ * >
+ *   <p>This is the content of the panel.</p>
+ * </Panel>
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/docs/core-components-panel--docs} for more details.
+ */
 export const Panel = ({
   children,
   className,
@@ -146,7 +182,7 @@ export const Panel = ({
   return (
     <div
       className={classNames(
-        classes.panel,
+        "fabric-panel",
         className,
         "rounded-capped overflow-hidden outline grid",
         expanded ? "fixed inset-4 z-50" : "relative",
@@ -172,16 +208,17 @@ export const Panel = ({
       <header
         role="none"
         className={classNames(
-          classes.panelHeader,
+          "fabric-panelHeader",
           headerClassName,
           "flex flex-nowrap items-center area-head",
         )}
+        data-ref="panelHeader"
         onClick={collapsable ? toggleCollapse : undefined}
       >
         {onBack && (
           <Icon
             data-ref="panelBack"
-            className={classNames(classes.panelAction, "cursor-pointer")}
+            className={classNames("fabric-panelAction", "cursor-pointer")}
             icon={CoreIcons.chevronLeft}
             onClick={onBack}
           />
@@ -204,7 +241,7 @@ export const Panel = ({
         >
           {title}
         </div>
-        <div className="px-1">{actions}</div>
+        <div className="px-1 leading-none">{actions}</div>
         {hasTools && (
           <div
             role="none"
@@ -214,7 +251,7 @@ export const Panel = ({
             {expandable && (
               <Icon
                 data-ref="panelExpand"
-                className={classNames(classes.panelAction, "cursor-pointer")}
+                className={classNames("fabric-panelAction", "cursor-pointer")}
                 icon={expanded ? CoreIcons.minimize : CoreIcons.maximize}
                 onClick={toggleExpand}
               />
@@ -222,7 +259,7 @@ export const Panel = ({
             {!expanded && collapsable && (
               <Icon
                 data-ref="panelCollapse"
-                className={classNames(classes.panelAction, "cursor-pointer")}
+                className={classNames("fabric-panelAction", "cursor-pointer")}
                 icon={collapsed ? CoreIcons.expand : CoreIcons.collapse}
                 onClick={toggleCollapse}
               />
@@ -230,7 +267,7 @@ export const Panel = ({
             {!expanded && onClose && (
               <Icon
                 data-ref="panelClose"
-                className={classNames(classes.panelAction, "cursor-pointer")}
+                className={classNames("fabric-panelAction", "cursor-pointer")}
                 icon={CoreIcons.close}
                 onClick={onClose}
               />
@@ -240,8 +277,9 @@ export const Panel = ({
       </header>
       {(!collapsed || expanded) && (
         <div
+          data-ref="panelBody"
           className={classNames(
-            classes.panelBody,
+            "fabric-panelBody",
             "area-content grid overflow-hidden",
           )}
         >

package/src/components/panel/PanelGroup.tsx

@@ -28,7 +28,6 @@ import {
   useMemoDebugger,
 } from "../../hooks/useEffectDebugger";
 import { type ChildrenProp } from "../../types";
-import classes from "./Panel.module.css";
 
 export interface PanelGroupProps extends ChildrenProp {
   /**
@@ -41,6 +40,30 @@ export interface PanelGroupProps extends ChildrenProp {
   onActiveChange?: (panelId: string) => void;
 }
 
+/**
+ * A component that groups multiple panels together, allowing for one panel to be expanded at a time.
+ * This component allows you to manage a group of panels where only one can be expanded at a time.
+ * It accepts an `activePanel` prop to control which panel is currently expanded,
+ * and an `onActiveChange` callback that is triggered when the active panel changes.
+ * It uses the `Panel` component to render each individual panel within the group.
+ *
+ * @param {PanelGroupProps} props - The properties for the PanelGroup component.
+ * @returns {JSX.Element} The rendered PanelGroup component.
+ *
+ * @example
+ * ```jsx
+ * <PanelGroup
+ *   activePanel="panel1"
+ *   onActiveChange={(panelId) => console.log(`Active panel changed to: ${panelId}`)}
+ * >
+ *   <Panel panelId="panel1" title="Panel 1">Content for Panel 1</Panel>
+ *   <Panel panelId="panel2" title="Panel 2">Content for Panel 2</Panel>
+ *   <Panel panelId="panel3" title="Panel 3">Content for Panel 3</Panel>
+ * </PanelGroup>
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/docs/core-components-panel--docs} for more details.
+ */
 export const PanelGroup = ({
   children,
   activePanel,
@@ -81,7 +104,7 @@ export const PanelGroup = ({
     <div
       data-ref="panelGroup"
       className={classNames(
-        classes.panelGroup,
+        "fabric-panelGroup",
         "flex flex-col overflow-auto area-content p-px",
       )}
     >

package/src/components/panel/PanelStack.tsx

@@ -49,6 +49,37 @@ export interface PanelStackProps extends CssProp, ChildrenProp {
   onBack?: (panelId: string, nextPanelId: string) => boolean | undefined;
 }
 
+/**
+ * A component that manages a stack of panels, allowing navigation between them.
+ * This component allows you to manage a stack of panels where you can navigate between them.
+ * It accepts an `active` prop to control which panel is currently active,
+ * an `onPanelChange` callback that is triggered when the active panel changes,
+ * and an `onBack` callback to handle navigation to the previous panel in the history.
+ * It uses the `Panel` component to render each individual panel within the stack.
+ * The component maintains a history of panels to allow back navigation,
+ * and it updates the active panel based on user interactions.
+ *
+ * @param {PanelStackProps} props - The properties for the PanelStack component.
+ * @returns {JSX.Element} The rendered PanelStack component.
+ *
+ * @example
+ * ```jsx
+ * <PanelStack
+ *   active="panel1"
+ *   onPanelChange={(panelId) => console.log(`Active panel changed to: ${panelId}`)}
+ *   onBack={(currentPanel, nextPanel) => {
+ *     console.log(`Navigating back from ${currentPanel} to ${nextPanel}`);
+ *     return true; // return false to prevent navigation
+ *   }}
+ * >
+ *   <Panel panelId="panel1" title="Panel 1">Content for Panel 1</Panel>
+ *   <Panel panelId="panel2" title="Panel 2">Content for Panel 2</Panel>
+ *   <Panel panelId="panel3" title="Panel 3">Content for Panel 3</Panel>
+ * </PanelStack>
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/docs/core-components-panelstack--docs} for more details.
+ */
 export const PanelStack = ({
   active,
   children,

package/src/components/progress/ProgressBar.tsx

@@ -24,13 +24,12 @@
 import { Format } from "@react-fabric/utilities";
 import classNames from "classnames";
 import { useMemoDebugger } from "../../hooks/useEffectDebugger";
-import { type ColorType } from "../../types";
-import { getColorClass } from "../../utils";
-import classes from "./Progress.module.css";
+import { type PaletteType, type ColorType } from "../../types";
+import { getColor } from "../../utils";
 
 export interface ProgressProps {
   /**
-   * progress value (0-100)
+   * progress value (0-1)
    */
   value: number;
   /**
@@ -40,7 +39,7 @@ export interface ProgressProps {
   /**
    * color
    */
-  color?: ColorType;
+  color?: ColorType | PaletteType;
   /**
    * animate
    */
@@ -61,23 +60,43 @@ const SizeMap: KeyValue = {
   xl: "2rem",
 };
 
+/**
+ * A component that displays a progress bar indicating the completion percentage of a task or operation.
+ * The progress bar is styled with a background color and a track that fills based on the value provided.
+ * It can also display a label showing the percentage value.
+ * The label can be customized or hidden based on the props provided.
+ *
+ * @param {ProgressProps} props - The properties for the ProgressBar component.
+ * @returns {JSX.Element} The rendered ProgressBar component.
+ *
+ * @example
+ * ```jsx
+ * <ProgressBar value={0.75} size="md" color="primary-500" label="Loading" animate />
+ * // Renders a progress bar with 75% completion, medium size, primary color, and a label "Loading"
+ *
+ * <ProgressBar value={0.5} size="lg" color="success-500" />
+ * // Renders a progress bar with 50% completion, large size, and success color without a label
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/docs/core-components-progress--docs} for more details.
+ */
 export const ProgressBar = ({
   value = 0,
   size,
-  color = "primary",
+  color = "primary-500",
   label = "",
   animate,
 }: ProgressProps) => {
   /** ***************** make sure value is between 0 and 100 *******************/
   const actualValue = useMemoDebugger(
-    () => Math.min(Math.max(value, 0), 100),
+    () => Math.min(Math.max(value, 0), 1),
     [value],
     "ProgressBar value",
   );
 
   const progressVar = useMemoDebugger<KeyValue>(
     () => ({
-      "--progress": actualValue,
+      "--progress": actualValue * 100,
     }),
     [actualValue],
     "ProgressBar cssVar",
@@ -87,12 +106,12 @@ export const ProgressBar = ({
   return (
     <div
       className={classNames(
-        classes.progressbar,
-        getColorClass(color),
+        "fabric-progressbar",
         "block bg-dimmed relative rounded font-bold overflow-hidden whitespace-nowrap",
       )}
       style={{
         ...progressVar,
+        color: getColor(color),
         minHeight: SizeMap[size ?? ""],
         fontSize: SizeMap[size ?? ""],
       }}
@@ -101,20 +120,20 @@ export const ProgressBar = ({
     >
       {!["xxs", "xs", "sm"].includes(size ?? "") && (
         <div className="absolute inset-0 text-center z-0 align-top">
-          {label} {Format.percent(actualValue / 100)}
+          {label} {Format.percent(actualValue)}
         </div>
       )}
       <div
         className={classNames(
-          classes.progressTrack,
-          animate && classes.progressAnimate,
+          "fabric-progressTrack",
+          animate && "fabric-progressAnimate",
           "h-full overflow-clip bg-current relative z-0",
         )}
       />
       {!["xxs", "xs", "sm"].includes(size ?? "") && (
         <div
           className={classNames("h-full absolute inset-0 overflow-hidden z-1")}
-          data-label={`${label} ${Format.percent(actualValue / 100)}`}
+          data-label={`${label} ${Format.percent(actualValue)}`}
         />
       )}
     </div>