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

package/src/core/viewport/Viewport.tsx

@@ -23,17 +23,30 @@
 
 import classNames from "classnames";
 import { type PropsWithChildren } from "react";
-import classes from "./Viewport.module.css";
 
 /**
- * The application viewport is the main container that defines the visible area where content is displayed and interacted with.
+ * This component is used to create a full-screen viewport
+ * that can be used to display content in a grid layout.
+ * It is typically used as a container for the main content of the application.
+ * It is styled to take up the full width and height of the viewport,
+ * and it uses absolute positioning to ensure it covers the entire screen.
+ * The component accepts children as props, allowing you to nest other components inside it.
+ *
+ * @example
+ * ```jsx
+ * <Viewport>
+ *   <YourContentComponent />
+ * </Viewport>
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/docs/core-application--viewport} for more details.
  */
 export const Viewport = ({ children }: PropsWithChildren) => {
   return (
     <div
       data-ref="viewport"
       className={classNames(
-        classes.viewport,
+        "fabric-viewport",
         "grid overflow-hidden absolute inset-0",
       )}
     >

package/src/hooks/useControlledValue.tsx

@@ -24,6 +24,18 @@
 import { useDeferredValue, useState } from "react";
 import { useEffectDebugger } from "./useEffectDebugger";
 
+/**
+ * Custom hook to manage a controlled value with a default fallback for inputs.
+ * It updates the current value whenever the deferred value changes.
+ * This is useful for scenarios where you want to control the value of a component
+ * while also providing a default value if the controlled value is not set.
+ * This hook is particularly useful for form inputs or components that require a controlled value
+ * but also need to handle cases where the value might not be immediately available.
+ *
+ * @param value - The controlled value that may change.
+ * @param defaultValue - The default value to use if the controlled value is not set.
+ * @returns An object containing the current value and a function to update it.
+ */
 export const useControlledValue = <T extends AnyObject = string>(
   value: T,
   defaultValue: T,

package/src/hooks/useDebounce.ts

@@ -23,12 +23,24 @@
 
 import { useMemo, useRef } from "react";
 
+/**
+ * Custom hook to debounce a function.
+ * This hook delays the processing of the function until after a specified delay period
+ * has elapsed since the last time the function was invoked. This is useful for optimizing
+ * performance in scenarios where a function may be called frequently, such as during
+ * user input or window resizing events.
+ *
+ * @param callback - The function to debounce.
+ * @param deps - The dependency array for the hook.
+ * @param delay - The debounce delay in milliseconds.
+ * @returns A debounced version of the callback function.
+ */
 export const useDebounce = (
   callback: undefined | ((...rest: AnyObject) => AnyObject),
   deps: AnyObject[],
   delay: number = 100,
 ) => {
-  const timerRef = useRef<AnyObject>();
+  const timerRef = useRef<AnyObject>(null);
 
   const cb = useMemo(() => {
     if (typeof window !== "undefined") {

package/src/hooks/useEffectDebugger.ts

@@ -44,10 +44,9 @@ const compareInputs = (
   logger: ReturnType<typeof useLogger>,
 ) => {
   if (
-    process.env.NODE_ENV === "production" &&
     typeof window !== "undefined" &&
     // @ts-expect-error ignore
-    window.DEBUG_HOOKS !== true
+    window.DEBUG_EFFECTS !== true
   )
     return;
 
@@ -87,6 +86,19 @@ const compareInputs = (
   });
 };
 
+/**
+ * Custom hook to debug useMemo hooks.
+ * It compares the current and previous dependency arrays and logs any differences.
+ * @param func - The function to be memoized or executed in the effect.
+ * @param inputs - The dependency array for the hook.
+ * @param prefix - A prefix for the log messages to identify the hook.
+ * @returns The result of the memoized function or the effect.
+ *
+ * @example
+ * ```jsx
+ * const value = useMemoDebugger(() => computeValue(), [dependency1, dependency2], "MyComponent");
+ * ```
+ */
 export const useMemoDebugger = <T>(
   func: () => T,
   inputs: DependencyList,
@@ -109,6 +121,24 @@ export const useMemoDebugger = <T>(
   }, inputs);
 };
 
+/**
+ * Custom hook to debug useEffect and useLayoutEffect hooks.
+ * It compares the current and previous dependency arrays and logs any differences.
+ * @param func - The effect function to be executed.
+ * @param inputs - The dependency array for the effect.
+ * @param prefix - A prefix for the log messages to identify the effect.
+ * @returns A cleanup function if the effect returns one.
+ *
+ * @example
+ * ```jsx
+ * useEffectDebugger(() => {
+ *   // Effect logic here
+ *   return () => {
+ *     // Cleanup logic here
+ *   };
+ * }, [dependency1, dependency2], "MyComponent");
+ * ```
+ */
 export const useEffectDebugger = (
   func: EffectCallback,
   inputs: DependencyList,
@@ -131,6 +161,24 @@ export const useEffectDebugger = (
   }, inputs);
 };
 
+/**
+ * Custom hook to debug useLayoutEffect hooks.
+ * It compares the current and previous dependency arrays and logs any differences.
+ * @param func - The layout effect function to be executed.
+ * @param inputs - The dependency array for the layout effect.
+ * @param prefix - A prefix for the log messages to identify the layout effect.
+ * @returns A cleanup function if the layout effect returns one.
+ *
+ * @example
+ * ```jsx
+ * useLayoutEffectDebugger(() => {
+ *   // Layout effect logic here
+ *   return () => {
+ *     // Cleanup logic here
+ *   };
+ * }, [dependency1, dependency2], "MyComponent");
+ * ```
+ */
 export const useLayoutEffectDebugger = (
   func: EffectCallback,
   inputs: DependencyList,

package/src/hooks/useIsDark.ts

@@ -24,6 +24,14 @@
 import { useCallback, useState } from "react";
 import { useLayoutEffectDebugger } from "./useEffectDebugger";
 
+/**
+ * Custom hook to determine if the current theme is dark.
+ * It checks the background color of the document's root element
+ * and sets the `isDark` state based on the red component of the RGB color.
+ * If the red component is less than 50, it considers the theme to be dark.
+ *
+ * @returns {boolean} - Returns true if the theme is dark, false otherwise.
+ */
 export const useIsDark = () => {
   const [isDark, setDark] = useState(false);
   const checkTheme = useCallback(() => {

package/src/hooks/useIsRtl.ts

@@ -25,6 +25,18 @@ import { useState } from "react";
 import { useTranslation } from "react-i18next";
 import { useLayoutEffectDebugger } from "./useEffectDebugger";
 
+/**
+ * Custom hook to determine if the current locale is RTL (Right-to-Left).
+ * It uses the i18n instance from react-i18next to check the direction.
+ *
+ * @returns {boolean} - Returns true if the current locale is RTL, false otherwise.
+ *
+ * @example
+ * ```jsx
+ * const isRtl = useIsRtl();
+ * // This will return true if the current locale is RTL, false otherwise.
+ * ```
+ */
 export const useIsRtl = () => {
   const { i18n } = useTranslation("core");
   const [isRtl, setIsRtl] = useState(false);

package/src/hooks/useNavigator.tsx

@@ -21,24 +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 { useCallback, useMemo, useState } from "react";
+import { useCallback, useMemo, useRef, useState } from "react";
 
+/**
+ * Custom hook to manage navigation through a list of items.
+ * It provides functionality to navigate forward and backward,
+ * and keeps track of the current index and total count of items.
+ *
+ * @param totalCount - Total number of items to navigate through.
+ * @param defaultIndex - Initial index to start navigation from.
+ * @returns An object containing the current index, a function to navigate,
+ *          a label for the current position, and a function to set the current index.
+ *
+ * @example
+ * ```jsx
+ * const { headLabel, onNavigate, currentIndex, setCurrentIndex } = useNavigator(5, 0);
+ * // headLabel will show "1/5"
+ * // onNavigate(1) will move to the next item, and onNavigate(-1) will move to the previous item.
+ * // currentIndex will be updated accordingly.
+ * ```
+ */
 export const useNavigator = (totalCount = 0, defaultIndex = 0) => {
   const [currentIndex, setCurrentIndex] = useState(defaultIndex);
+  const refCurrent = useRef(defaultIndex);
+
   const onNavigate = useCallback(
     (dir: 1 | -1) => {
       if (dir === -1) {
-        setCurrentIndex(currentIndex > 0 ? currentIndex - 1 : totalCount - 1);
+        refCurrent.current =
+          refCurrent.current > 0 ? refCurrent.current - 1 : totalCount - 1;
       }
       if (dir === 1) {
-        setCurrentIndex(currentIndex + 1 < totalCount ? currentIndex + 1 : 0);
+        refCurrent.current =
+          refCurrent.current + 1 < totalCount ? refCurrent.current + 1 : 0;
       }
+      setCurrentIndex(refCurrent.current);
     },
-    [currentIndex, totalCount],
+    [totalCount],
   );
   const headLabel = useMemo(
     () => (
-      <span className="text-muted leading-none">
+      <span className="text-muted leading-none select-none">
         {currentIndex + 1}/{totalCount}
       </span>
     ),

package/src/hooks/useOverlayService.tsx

@@ -21,13 +21,40 @@
  * 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,
+  type ReactNode,
+} 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,
 ): [
@@ -36,7 +63,10 @@ export const useOverlayService = (
 ] => {
   const [Overlay, setOverlay] = useState<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/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

@@ -40,9 +40,13 @@ 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,11 +36,10 @@ 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, type IconProps } 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"> {
   /**
@@ -58,7 +57,7 @@ export interface AlertProps extends Omit<IconProps, "iconBg" | "iconColor"> {
   /**
    * theme color
    */
-  color?: ColorType;
+  color?: ColorState;
   /**
    * extra action button
    */
@@ -116,35 +115,20 @@ export const Alert = ({
   const iconType = useMemo(() => {
     if (icon)
       return (
-        <Icon icon={icon} size="md" rtlFlip={rtlFlip} color={color + "-600"} />
+        <Icon icon={icon} 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`}
           />
         );
     }
@@ -172,17 +156,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 +176,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 +224,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>