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

package/src/hooks/useOverlayService.tsx

@@ -21,22 +21,47 @@
  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-import { useState, type FC, type ReactNode } from "react";
+import { useState, type ComponentProps, type ElementType } from "react";
+import { type ModalProps } from "../types";
 
-type OverlayComponent = FC<{
-  onClose: (args?: AnyObject) => void;
-  [key: string]: AnyObject;
-}>;
+type OverlayComponent = ElementType<ModalProps<AnyObject>>;
 
+/**
+ * Hook to manage overlay components like modals or flyouts.
+ * It provides a way to open an overlay with specified properties and handle its closure.
+ * This hook returns the current overlay component and a function to open it with props.
+ * It is useful for scenarios where you need to display overlays dynamically,
+ * such as modals, flyouts, or any other overlay components in a React application.
+ * The `openOverlay` function returns a promise that resolves with the result
+ * of the overlay when it is closed, allowing you to handle the result in a controlled manner.
+ *
+ * @param ModalOrFlyout - The component to be used as an overlay.
+ * @returns An array containing the current overlay and a function to open it.
+ *
+ * @example
+ * ```jsx
+ * const [Overlay, openOverlay] = useOverlayService(MyModalComponent);
+ * // To open the overlay:
+ * const handleOpen = async () => {
+ *   const result = await openOverlay({ title: "My Modal", content: "Hello World" });
+ *   console.log(result); // Handle the result from the overlay
+ * };
+ * <button onClick={handleOpen}>Open Modal</button>
+ * <Overlay />
+ * ```
+ */
 export const useOverlayService = (
   ModalOrFlyout: OverlayComponent,
 ): [
-  Overlay: ReactNode | null,
+  Overlay: React.ReactNode | null,
   openOverlay: (props?: KeyValue) => Promise<AnyObject>,
 ] => {
-  const [Overlay, setOverlay] = useState<ReactNode | null>(null);
+  const [Overlay, setOverlay] = useState<React.ReactNode | null>(null);
 
-  const openOverlay = async ({ onClose, ...props }: KeyValue = {}) => {
+  const openOverlay = async ({
+    onClose,
+    ...props
+  }: ComponentProps<typeof ModalOrFlyout> = {}) => {
     return await new Promise((resolve) => {
       const handleClose = (args: AnyObject) => {
         setOverlay(null);

package/src/hooks/usePropToggle.ts

@@ -25,11 +25,22 @@ import { useCallback, useRef, useState, type RefObject } from "react";
 import { useLayoutEffectDebugger } from "./useEffectDebugger";
 
 /**
- * hook to control boolean props
- * @param isOn (is prop true)
- * @param callback (optional callback)
- * @param key (optional key to pass to callback)
- * @returns
+ * This hook is used to manage a toggle state based on a prop value.
+ * It allows you to toggle the state and also provides a reference to the current state.
+ * It is useful for scenarios where you want to control a toggle state from a parent component while also allowing local toggling.
+ *
+ * @param isOn - Initial state of the toggle (default: false)
+ * @param onToggle - Callback function that is called when the toggle state changes.
+ * @param key - Optional key to identify the toggle state, useful for multiple toggles.
+ * @returns A tuple containing the current toggle state, a function to toggle the state, and a reference to the current state.
+ *
+ * @example
+ * ```jsx
+ * const [isToggled, toggle, toggleRef] = usePropToggle(false, (newState) => {
+ *   console.log("Toggle state changed to:", newState);
+ * });
+ * toggle(); // This will toggle the state and call the onToggle callback
+ * ```
  */
 export const usePropToggle = (
   isOn = false,

package/src/hooks/useResize.ts

@@ -43,10 +43,28 @@ interface Options {
   onEnd?: () => void;
 }
 
+/**
+ * Custom hook to handle resizing of an element.
+ * It provides a ref to the element and a mouse down event handler to initiate resizing.
+ * The resizing is done by tracking mouse movements and calculating the difference in x and y coordinates.
+ * It supports both horizontal and vertical resizing, and can be configured to reverse the direction based on RTL (Right-to-Left) layout.
+ *
+ * @param onResize - callback to handle resize event with the difference in x and y
+ * @param options - options for resizing behavior
+ * @returns ref to the element and a mouse down event handler to initiate resizing
+ *
+ * @example
+ * ```jsx
+ * const { ref, onMouseDown } = useResize((diff) => {
+ *   console.log("Resize difference:", diff);
+ * }, { isReverse: true, isVertical: false });
+ * <div ref={ref} onMouseDown={onMouseDown}>Resize Me</div>
+ * ```
+ */
 export const useResize = <T extends HTMLElement = HTMLDivElement>(
   onResize: (diff: { x: number; y: number }) => void,
   { isReverse = false, isVertical = false, onStart, onEnd }: Options,
-): { ref: RefObject<T>; onMouseDown: React.MouseEventHandler } => {
+): { ref: RefObject<T | null>; onMouseDown: React.MouseEventHandler } => {
   const refEl = useRef<T>(null);
   const isRtl = useIsRtl();
 

package/src/hooks/useResizeObserver.ts

@@ -26,20 +26,43 @@ import ResizeObserver from "resize-observer-polyfill";
 import { type SizeObject } from "../types";
 import { useDebounce } from "./useDebounce";
 
+/**
+ * Custom hook to observe size changes of an element using ResizeObserver.
+ * It returns a ref that can be attached to the element you want to observe.
+ * The hook will call the provided `onResize` callback with the new size of the element
+ * whenever it changes.
+ * * This is useful for responsive designs where you need to adjust the layout or styles
+ * based on the size of an element.
+ *
+ * @param onResize Callback function that receives the new size of the element.
+ * @returns A ref object to be attached to the element you want to observe.
+ *
+ * @example
+ * ```jsx
+ * const ref = useResizeObserver((size) => {
+ *   console.log("Element resized:", size);
+ * });
+ * <div ref={ref}>Resize me!</div>
+ * ```
+ */
 export const useResizeObserver = <T extends HTMLElement = HTMLDivElement>(
   onResize?: (size: SizeObject) => void,
-): RefObject<T> => {
+): RefObject<T | null> => {
   const ref = useRef<T>(null);
   const [, startTransition] = useTransition();
 
-  const callbackResize = useDebounce(() => {
-    startTransition(() => {
-      if (onResize && ref.current != null) {
-        const { offsetWidth: width, offsetHeight: height } = ref.current;
-        onResize?.({ width, height });
-      }
-    });
-  }, [onResize]);
+  const callbackResize = useDebounce(
+    () => {
+      startTransition(() => {
+        if (onResize && ref.current != null) {
+          const { offsetWidth: width, offsetHeight: height } = ref.current;
+          onResize?.({ width, height });
+        }
+      });
+    },
+    [onResize],
+    0,
+  );
 
   useEffect(() => {
     if (ref.current != null) {

package/src/hooks/useStepper.tsx

@@ -0,0 +1,68 @@
+/*
+ * 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 { useMemo, useState } from "react";
+import { Icon } from "../components";
+
+export const useStepper = ({
+  steps,
+  activeStep: _initialActiveStep = 0,
+}: {
+  steps: Array<{ label?: React.ReactNode; icon?: React.ReactNode }>;
+  activeStep?: number;
+}) => {
+  const [activeStep, setActiveStep] = useState(_initialActiveStep);
+  const maxSteps = useMemo(() => steps.length - 1, [steps]);
+
+  const stepper = useMemo(() => {
+    return (
+      <div className="fabric-stepper bg-base flex-1 flex justify-center py-1 px-2 overflow-x-auto">
+        {steps.map((child: any, index) => (
+          <div
+            className="fabric-stepper--pill"
+            key={index}
+            data-state={
+              index === activeStep
+                ? "active"
+                : index < activeStep
+                  ? "completed"
+                  : undefined
+            }
+          >
+            {child.icon && <Icon icon={child.icon} />}
+            {child.label && <label>{child.label}</label>}
+          </div>
+        ))}
+      </div>
+    );
+  }, [steps]);
+
+  return {
+    stepper,
+    activeStep,
+    firstStep: activeStep === 0,
+    lastStep: activeStep === maxSteps,
+    next: () => setActiveStep((s) => Math.min(s + 1, maxSteps)),
+    prev: () => setActiveStep((s) => Math.max(s - 1, 0)),
+  };
+};

package/src/hooks/useStorage.ts

@@ -25,6 +25,24 @@ import { useState } from "react";
 import { useClientService } from "./useClientService";
 import { useEffectDebugger } from "./useEffectDebugger";
 
+/**
+ * Custom hook to manage local storage state.
+ * This hook allows you to store and retrieve values from the browser's local storage,
+ * and provides a way to update the stored value while keeping the state in sync with local storage.
+ * It initializes the state with the value from local storage if it exists, or uses a default value if it does not.
+ * The hook returns a tuple containing the current value and a function to update the value.
+ * This is useful for persisting user preferences or application state across page reloads.
+ *
+ * @param key - The key under which the value is stored in local storage.
+ * @param defaultValue - The default value to use if the key does not exist in local storage.
+ * @returns A tuple containing the current value and a function to update the value.
+ *
+ * @example
+ * ```jsx
+ * const [settings, setSettings] = useLocalStorage("userSettings", { theme: "light" });
+ * // This will initialize the settings state from local storage or use the default value.
+ * ```
+ */
 export const useLocalStorage = <T>(
   key: string,
   defaultValue: T,
@@ -50,6 +68,26 @@ export const useLocalStorage = <T>(
   return [value, changeValue];
 };
 
+/**
+ * Custom hook to manage session storage state.
+ * This hook allows you to store and retrieve values from the browser's session storage,
+ * and provides a way to update the stored value while keeping the state in sync with session storage.
+ * It initializes the state with the value from session storage if it exists, or uses a default value if it does not.
+ * The hook returns a tuple containing the current value and a function to update the value.
+ * This is useful for persisting user preferences or application state during a single session,
+ * such as form data or temporary settings that should not persist across page reloads.
+ * This hook is similar to `useLocalStorage`, but it uses session storage instead of local storage.
+ *
+ * @param key - The key under which the value is stored in session storage.
+ * @param defaultValue - The default value to use if the key does not exist in session storage.
+ * @returns A tuple containing the current value and a function to update the value.
+ *
+ * @example
+ * ```jsx
+ * const [user, setUser] = useSessionStorage("user", { name: "", age: 0 });
+ * // This will initialize the user state from session storage or use the default value.
+ * ```
+ */
 export const useSessionStorage = <T>(
   key: string,
   defaultValue: T,

package/src/hotkeys/HotKeyLabel.tsx

@@ -54,7 +54,7 @@ export const HotKeyLabel = ({
   );
 
   return (
-    <kbd className="hotkey-label inline-flex gap-1 select-none self-center font-mono items-center text-[0.625rem] leading-4 bg-tint-500/10 text-base/50 whitespace-nowrap rounded px-2 mx-1">
+    <kbd className="hotkey-label inline-flex gap-1 select-none self-center font-mono items-center text-[0.625rem] leading-4 bg-tint-500/20 text-tint-900/65 whitespace-nowrap rounded px-2 mx-1">
       {label}
     </kbd>
   );

package/src/hotkeys/HotKeyWrapper.tsx

@@ -76,7 +76,9 @@ export const HotKeyWrapper: FC<PropsWithChildren> = memo(
       const find = items.find(
         ({ key, alt, ctrl, meta, shift }: KeyValue) =>
           (key.toLowerCase() === keyCode.toLowerCase() ||
-            key.toLowerCase() === code.toLowerCase()) &&
+            key.toLowerCase() === code.toLowerCase() ||
+            // work around for macos alt+key issue
+            `key${key.toLowerCase()}` === code.toLowerCase()) &&
           alt === altKey &&
           ctrl === ctrlKey &&
           meta === metaKey &&

package/src/index.ts

@@ -36,13 +36,18 @@ export * from "./hooks/useNavigator";
 export * from "./hooks/useOverlayService";
 export * from "./hooks/useResize";
 export * from "./hooks/useResizeObserver";
+export * from "./hooks/useStepper";
 export * from "./hooks/useStorage";
 
 export { HotKey } from "./hotkeys/HotKey";
 export { HotKeyLabel } from "./hotkeys/HotKeyLabel";
+export { HotKeyWrapper } from "./hotkeys/HotKeyWrapper";
 
+export { type ModalProps } from "./types";
 export { CoreIcons } from "./types/icons";
 
+export { cloneChildren } from "./utils";
+
 export {
   ApplicationProvider,
   useApplicationContext,

package/src/overlays/alert/Alert.tsx

@@ -36,17 +36,28 @@ import { useTranslation } from "react-i18next";
 import { AnimationIndicator } from "../../components/animations/Animations";
 import { Button } from "../../components/button/Button";
 import { Icon } from "../../components/icon/Icon";
-import { type ColorType, type Elements, type IconProps } from "../../types";
+import { type ColorState, type Elements } from "../../types";
 import { CoreIcons } from "../../types/icons";
 import { Title } from "../../typography/Title";
-import { getBorderClass, getColorClass } from "../../utils";
-import classes from "./Alert.module.css";
+import { getColor } from "../../utils";
 
-export interface AlertProps extends Omit<IconProps, "iconBg" | "iconColor"> {
+export interface AlertProps {
   /**
    * toast type
    */
   type?: "alert" | "confirm" | "prompt";
+  /**
+   * svg path / webfont className / 1-4 letter text
+   */
+  icon?: string;
+  /**
+   * icon image source URL, if failed to load then shows icon
+   */
+  iconSrc?: string;
+  /**
+   * flip icon in rtl
+   */
+  rtlFlip?: boolean;
   /**
    * toast title
    */
@@ -58,7 +69,7 @@ export interface AlertProps extends Omit<IconProps, "iconBg" | "iconColor"> {
   /**
    * theme color
    */
-  color?: ColorType;
+  color?: ColorState;
   /**
    * extra action button
    */
@@ -86,9 +97,11 @@ export const Alert = ({
   message,
   color = "primary",
   icon,
+  iconSrc,
   rtlFlip,
   actions,
   // @ts-expect-error internal prop
+  // eslint-disable-next-line react/prop-types --- IGNORE ---
   onClose,
   type,
   okLabel,
@@ -116,39 +129,30 @@ export const Alert = ({
   const iconType = useMemo(() => {
     if (icon)
       return (
-        <Icon icon={icon} size="md" rtlFlip={rtlFlip} color={color + "-600"} />
+        <Icon
+          icon={icon}
+          iconSrc={iconSrc}
+          size="md"
+          rtlFlip={rtlFlip}
+          color={`${color}-600`}
+        />
       );
     switch (color) {
       case "danger":
-        return (
-          <AnimationIndicator
-            type="cross"
-            className={getColorClass(color + "-600")}
-          />
-        );
+        return <AnimationIndicator type="cross" color={"danger-600"} />;
       case "success":
-        return (
-          <AnimationIndicator
-            type="check"
-            className={getColorClass(color + "-600")}
-          />
-        );
+        return <AnimationIndicator type="check" color={"success-600"} />;
       case "warning":
-        return (
-          <AnimationIndicator
-            type="exclaim"
-            className={getColorClass(color + "-600")}
-          />
-        );
+        return <AnimationIndicator type="exclaim" color={"warning-600"} />;
       default:
         return (
           <AnimationIndicator
             type={type === "confirm" ? "question" : "info"}
-            className={getColorClass(color + "-600")}
+            color={`${color}-600`}
           />
         );
     }
-  }, [color, type, icon]);
+  }, [color, type, icon, iconSrc, rtlFlip]);
 
   const handleClose = useCallback(
     (ret: AnyObject) => {
@@ -172,17 +176,19 @@ export const Alert = ({
       <FloatingOverlay
         lockScroll
         style={{ zIndex: "var(--z-overlay-mask)" }}
-        className="bg-base/50 backdrop-blur-sm grid place-items-center"
+        className="bg-tint-100/50 backdrop-blur-sm grid place-items-center"
       >
         <FloatingFocusManager context={context}>
           <dialog
             role="alertdialog"
             className={classNames(
-              classes.alert,
-              getBorderClass(color + "-300"),
+              "fabric-alert",
               "grid bg-base border-2 pointer-events-auto overflow-hidden rounded-capped select-none",
               "min-w-72 max-w-sm p-6 relative outline-0 shadow-lg",
             )}
+            style={{
+              borderColor: getColor(`${color}-300`),
+            }}
             ref={refs.setFloating}
             {...getFloatingProps()}
           >
@@ -190,16 +196,26 @@ export const Alert = ({
               {iconType}
             </div>
 
-            <Title className="font-medium area-[title]">{title}</Title>
-            <p className="area-[message] py-4">{message}</p>
+            <Title className="font-medium area-[title] self-center">
+              {title}
+            </Title>
+            <div className="area-[message] py-4">{message}</div>
             {type === "prompt" && (
               <input
                 value={value}
                 placeholder={placeholder}
                 className={classNames(
-                  "border rounded focus:border-primary-500",
+                  `area-[input] appearance-none outline-0 border rounded w-full px-2 py-1`,
                 )}
-                ref={(e) => e != null && setTimeout(() => e.focus(), 100)}
+                style={
+                  {
+                    borderColor: getColor(`${color}-200`),
+                    "--tw-ring-color": getColor(`${color}-500`),
+                  } as AnyObject
+                }
+                ref={(e) => {
+                  e != null && setTimeout(() => e.focus(), 100);
+                }}
                 onBlur={(e) => e.target.focus()}
                 onChange={(e) => setValue(e.target.value)}
                 onKeyDown={(e) => e.key === "Enter" && handleClose(value)}
@@ -228,7 +244,7 @@ export const Alert = ({
                 size="sm"
                 variant="solid"
                 color={color}
-                onClick={() => handleClose(true)}
+                onClick={() => handleClose(type === "prompt" ? value : true)}
               >
                 {okLabel ?? t("action.ok", "OK")}
               </Button>