@react-fabric/core 1.0.0-beta.9 → 1.0.1

package/src/components/flyout/Flyout.tsx

@@ -0,0 +1,257 @@
+/*
+ * React Fabric
+ * @version: 1.0.0
+ *
+ *
+ * The MIT License (MIT)
+ * Copyright (c) 2024 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 {
+  FloatingFocusManager,
+  FloatingOverlay,
+  FloatingPortal,
+  useDismiss,
+  useFloating,
+  useInteractions,
+  useRole,
+} from "@floating-ui/react";
+import { cn } from "@react-fabric/utilities";
+import { Activity, use, useEffect, useId } from "react";
+import { LoadingLine } from "../../components/animations/LoadingLine";
+import { Icon } from "../../components/icon/Icon";
+import { ModalContext } from "../../context/context";
+import type { CallbackReturn, ChildrenProp, CssPropWithMap, TestProps } from "../../types";
+import type { TitlebarProps } from "../titlebar/Titlebar";
+import { Titlebar } from "../titlebar/Titlebar";
+
+export interface FlyoutProps<T>
+  extends
+    TestProps,
+    ChildrenProp,
+    TitlebarProps,
+    CssPropWithMap<{ root: string; body?: string; titlebar?: string; title?: string; icon?: string }> {
+  /**
+   * flyout alignment
+   */
+  align?: "start" | "end" | "top" | "bottom";
+  /**
+   * show loading indicator
+   */
+  loading?: boolean;
+  /**
+   * modal size
+   */
+  size?: "sm" | "md" | "lg" | "xl" | "screen";
+  /**
+   * width
+   */
+  width?: string | number;
+  /**
+   * minimum width
+   */
+  minWidth?: string | number;
+  /**
+   * height
+   */
+  height?: string | number;
+  /**
+   * minimum height
+   */
+  minHeight?: string | number;
+  /**
+   * portal root element
+   */
+  root?: HTMLElement;
+  /**
+   * hide backdrop mask
+   */
+  hideMask?: boolean;
+  /**
+   * close flyout on any click
+   */
+  closeOnClick?: boolean;
+  closeOnEscape?: boolean;
+  /**
+   * close handler
+   */
+  onClose?: (args: T | null) => void;
+  /**
+   * before close handler, return false to prevent close
+   */
+  onBeforeClose?: (args: T | null) => CallbackReturn;
+}
+
+const AlignmentClasses = {
+  start: "inset-s-0 inset-y-0",
+  end: "inset-e-0 inset-y-0",
+  top: "top-0 inset-x-0",
+  bottom: "bottom-0 inset-x-0",
+};
+
+export function Flyout<T extends AnyObject = AnyObject>({
+  icon,
+  className,
+  classNames,
+  closeOnEscape,
+  title,
+  actions,
+  closeOnClick,
+  onClose,
+  onBeforeClose,
+  children,
+  loading,
+  size,
+  width,
+  minWidth,
+  height,
+  minHeight,
+  root,
+  hideMask,
+  align = "start",
+  ...props
+}: FlyoutProps<T>) {
+  const id = useId();
+  const { activeModal, registerModal, removeModal } = use(ModalContext);
+  const { refs, context } = useFloating({
+    open: true,
+    onOpenChange: () => {
+      handleClose(null);
+    },
+  });
+  const dismiss = useDismiss(context, {
+    outsidePressEvent: "mousedown",
+    outsidePress: !hideMask,
+    escapeKey: closeOnEscape,
+  });
+  const role = useRole(context);
+
+  // Merge all the interactions into prop getters
+  const { getFloatingProps } = useInteractions([dismiss, role]);
+
+  const handleClose = (args: T | null) => {
+    void Promise.resolve(onBeforeClose?.(args)).then((ret) => {
+      if (ret !== false) {
+        if (refs.floating.current) refs.floating.current.dataset.show = "false";
+        setTimeout(() => {
+          onClose?.(args);
+        }, 250);
+      }
+      if (ret === false) setTimeout(() => refs.floating.current?.querySelector<HTMLElement>("[role='dialog']")?.focus(), 50);
+    });
+  };
+
+  useEffect(() => {
+    if (activeModal === id) {
+      const tmr = setTimeout(() => {
+        if (refs.floating.current) refs.floating.current.dataset.show = "true";
+      }, 50);
+
+      return () => {
+        clearTimeout(tmr);
+      };
+    }
+  }, [activeModal, id, refs.floating]);
+
+  const tryClosing = (e: React.MouseEvent) => {
+    if (!!closeOnClick || (e.target as HTMLElement).closest("[data-flyout-dismiss='true']")) {
+      setTimeout(() => {
+        handleClose(null);
+      }, 100);
+    }
+  };
+
+  useEffect(() => {
+    registerModal?.(id, () => onClose?.(null));
+
+    return () => {
+      removeModal?.(id);
+    };
+    // eslint-disable-next-line @eslint-react/exhaustive-deps
+  }, [id]);
+
+  const isVertical = ["top", "bottom"].includes(align);
+
+  return (
+    <Activity mode={id === activeModal ? "visible" : "hidden"}>
+      <FloatingPortal root={root}>
+        {!hideMask && (
+          <FloatingOverlay
+            lockScroll
+            style={{ zIndex: "var(--z-overlay-mask)", overflow: "hidden" }}
+            className="bg-tint-100/10 backdrop-blur-sm transition-all"
+          />
+        )}
+        <FloatingFocusManager context={context} modal>
+          <div
+            data-align={align}
+            className={cn(
+              "fabric-flyout bg-default",
+              isVertical ? "h-32 max-h-[70vh]" : "w-lg max-w-[70vw]",
+              className,
+              classNames?.root,
+              "fixed overflow-hidden flex flex-col flex-nowrap pointer-events-auto shadow-xl",
+              AlignmentClasses[align],
+              size === "sm" && (isVertical ? "h-80" : "w-80"),
+              size === "md" && (isVertical ? "h-160" : "w-160"),
+              size === "lg" && (isVertical ? "h-[60vh]" : "w-[60vw]"),
+              size === "xl" && (isVertical ? "h-[80vh]" : "w-[80vw]"),
+            )}
+            style={
+              isVertical
+                ? {
+                    height,
+                    minHeight,
+                  }
+                : {
+                    width,
+                    minWidth,
+                  }
+            }
+            onMouseUpCapture={tryClosing}
+            ref={(el) => refs.setFloating(el)}
+            {...getFloatingProps()}
+            {...props}
+          >
+            <Titlebar
+              title={title}
+              icon={icon}
+              actions={
+                <>
+                  <div className="px-1 leading-none">{actions}</div>
+                  <button className="size-fit cursor-pointer leading-none outline-none" onClick={() => handleClose(null)}>
+                    <Icon
+                      data-ref="panelClose"
+                      className={cn("fabric-panelAction", "cursor-pointer p-1 text-xl self-center")}
+                      icon="icon-[mdi--close]"
+                    />
+                  </button>
+                </>
+              }
+              className={cn(classNames?.titlebar)}
+              classNames={classNames}
+            />
+            {loading && <LoadingLine />}
+            <div role="dialog" className={cn("fabric-flyoutBody", classNames?.body, "flex-1 grid overflow-hidden")}>
+              {children}
+            </div>
+          </div>
+        </FloatingFocusManager>
+      </FloatingPortal>
+    </Activity>
+  );
+}

package/src/components/hotkey/HotKey.tsx

@@ -0,0 +1,57 @@
+/**
+ * React Fabric
+ * @version 1.0.0
+ * @license MIT
+ * @copyright 2024 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 type { Hotkey } from "@tanstack/react-hotkeys";
+import { useHotkeySequence } from "@tanstack/react-hotkeys";
+
+export interface HotKeyProps {
+  /**
+   * Hot key combination
+   *
+   * ctrl, shift, alt, meta
+   * enter, space, escape, tab, backspace, delete
+   * left, right, up, down
+   */
+  keys: Hotkey | Hotkey[];
+  disabled?: boolean;
+  /**
+   * Callback handler
+   */
+  handler?: () => void;
+}
+
+export function HotKey({ keys, disabled, handler }: HotKeyProps) {
+  useHotkeySequence(
+    [keys].flat(),
+    () => {
+      void handler?.();
+    },
+    {
+      enabled: !disabled,
+    },
+  );
+
+  return null;
+}

package/src/components/icon/Icon.tsx

@@ -1,176 +1,177 @@
-/*
+/**
  * React Fabric
- * @version: 1.0.0
- *
- *
- * The MIT License (MIT)
- * Copyright (c) 2024 Adarsh Pastakia
+ * @version 1.0.0
+ * @license MIT
+ * @copyright 2024 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:
+ * 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 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.
+ * 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 { isString, isSvgPath } from "@react-fabric/utilities";
-import classNames from "classnames";
-import { useMemo } from "react";
-import {
-  type AriaProps,
-  type ColorType,
-  type CssProp,
-  type RefProp,
-  type SizeType,
-  type TestProps,
-} from "../../types";
-import { getBgClass, getColor, getColorClass } from "../../utils";
-import classes from "./Icon.module.css";
+import { cn, isString, isSvgPath } from "@react-fabric/utilities";
+import { isValidElement, useMemo } from "react";
+import type { CssProp, CSSSizeType, CustomColors, RefProp, TestProps } from "../../types";
+import { getColor } from "../../utils";
 
-export interface IconProps extends CssProp, AriaProps, RefProp, TestProps {
+export interface BaseIconProps extends CssProp, TestProps {
   /**
-   * svg path / webfont className / 1-4 letter text
+   * Icon can be a string or a React element. If it's a string, it can be either an SVG path or a CSS class name.
+   * If the string is a valid SVG path, it will be rendered as an inline SVG. If it's a CSS class name, it will be rendered as an <i> element with that class.
+   * If the string is 4 characters or less, it will be rendered as text inside an SVG, with font size adjusted based on the length of the string.
+   * If it's a React element, it will be rendered directly.
    */
-  icon: string;
+  icon: string | React.ReactElement;
   /**
-   * background color (CSS color / tailwind color)
+   * Background color applied to the badge. Accepts Tailwind palette tokens or any CSS color.
    */
-  bg?: ColorType | string;
+  bg?: CustomColors;
   /**
-   * icon color (CSS color / tailwind color)
+   * The color prop allows developers to specify the color of the icon.
+   * It can accept predefined color values from the design system, such as "primary-500" or "secondary-300", which correspond to specific colors in the palette.
+   * Additionally, it can also accept custom color values in standard CSS formats, such as hex codes (e.g., "#ff0000"), RGB (e.g., "rgb(255, 0, 0)"), or HSL (e.g., "hsl(0, 100%, 50%)"). This flexibility allows developers to easily integrate icons with their application's color scheme while also providing the option for custom styling when needed.
    */
-  color?: ColorType | string;
+  color?: CustomColors;
   /**
-   * flip icon in rtl
+   * The viewBox attribute defines the position and dimension, in user space, of an SVG viewport.
+   * It is required when the icon prop is an SVG path string to ensure the SVG scales correctly.
    */
-  rtlFlip?: boolean;
+  viewBox?: string;
   /**
-   * icon size
+   * The size property allows developers to specify the size of the icon, which can be defined using standard CSS size values such as pixels (e.g., "24px"), ems (e.g., "1.5em"), or percentages (e.g., "100%").
    */
-  size?: SizeType | number | string;
+  size?: CSSSizeType;
   /**
-   * viewbox for svg path (default 24)
+   * When true, the icon will be flipped horizontally in right-to-left (RTL) contexts.
+   * This is useful for icons that indicate direction, such as arrows, to ensure they point in the correct direction in RTL layouts.
    */
-  viewBox?: string;
+  rtlFlip?: boolean;
   /**
-   * rounded icon
+   * When true, the icon will have rounded corners.
    */
   rounded?: boolean;
   /**
-   * apply animation
+   * The animate prop can be used to apply animation effects to the icon.
+   * It accepts predefined animation values such as "spin", "fade", "pulse", or "bounce".
    */
-  animate?: "spin" | "pulse" | "bounce";
-  /**
-   * click handler
-   */
-  onClick?: React.MouseEventHandler;
+  animate?: "spin" | "fade" | "pulse" | "bounce";
 }
-
 const SvgTextSize = ["", ".875em", ".525em", ".35em", ".25em"];
-const SizeMap: KeyValue<string> = {
-  xs: "0.625rem",
-  sm: "0.875rem",
-  md: "1.125rem",
-  lg: "1.5rem",
-  xl: "2rem",
+
+export type IconProps = string | BaseIconProps | React.ReactElement;
+
+const ANIMATIONS = {
+  spin: "animate-spin",
+  fade: "animate-fade",
+  pulse: "animate-pulse",
+  bounce: "animate-bounce",
 };
 
 /**
- * An icon is a display component for svg icon path / image
+ * A versatile icon component that supports multiple formats: SVG paths, CSS class names,
+ * and short text labels (rendered inside an SVG).
+ *
+ * Recommended to use iconify for CSS icons
+ *
+ * @see https://iconify.design/ for a comprehensive collection of icons that can be easily integrated using CSS class names, providing a wide range of options for developers to choose from when selecting icons for their applications.
+ *
+ * @example
+ * ```tsx
+ * import { Icon } from "@react-fabric/core";
+ *
+ * // Render as a raw SVG path
+ * <Icon icon="M10 20v-6h4v6h5V3h-5V13H9v6H5v-6h4z" size="24px" />
+ *
+ * // Render via CSS class
+ * <Icon icon="icon-[mdi--home]" />
+ *
+ * // Render as a short text label inside an SVG
+ * <Icon icon="+" size="1.5em" />
+ *
+ * // With additional features like animations and custom colors
+ * <Icon icon="M4 10h2v10H4zm8-2h2v10h-2zm6-7h2v10h-2zm-4 12h2v3h-2z" animate="spin" color="primary-500" />
+ * ```
  */
-export const Icon = ({
-  ref,
-  icon,
-  bg,
-  color,
-  size = "",
-  rtlFlip,
+export function Icon({
   animate,
+  className,
+  color,
+  bg,
+  icon,
+  ref,
   rounded,
+  rtlFlip,
+  size,
   viewBox = "0 0 24 24",
-  className,
-  onClick,
-  ...rest
-}: IconProps) => {
-  /** ***************** style map *******************/
-  const styles = useMemo(() => {
-    const s: KeyValue = {};
-    if (bg) {
-      s.backgroundColor = getColor(bg);
-    }
-    if (color) {
-      s.color = getColor(color);
-    }
-    if (size && !(size in SizeMap)) {
-      s.fontSize = size;
-    }
-    if (size && size in SizeMap) {
-      s.fontSize = SizeMap[size];
-    }
-    return s;
-  }, [bg, color, size]);
-
-  /** ***************** check if icon is svg path *******************/
-  const isSvg = useMemo(() => {
-    return isSvgPath(icon);
-  }, [icon]);
-
-  /** ***************** render icon *******************/
+  ...props
+}: BaseIconProps & RefProp) {
   const iconEl = useMemo(() => {
-    if (!isString(icon)) {
-      throw Error("Invalid icon expected string");
+    if (isValidElement(icon)) return icon;
+    if (isString(icon)) {
+      if (isSvgPath(icon)) {
+        return (
+          <svg viewBox={viewBox} className="size-[1em]">
+            <path fill="currentColor" d={icon.toString()} />
+          </svg>
+        );
+      }
+
+      return icon.length <= 4 ? (
+        <svg role="img" className="size-[1em]">
+          <text
+            x="50%"
+            y="50%"
+            dy=".1em"
+            dominantBaseline="middle"
+            textAnchor="middle"
+            style={{ fontSize: SvgTextSize[icon.length] }}
+          >
+            {icon}
+          </text>
+        </svg>
+      ) : (
+        <i className={`size-[1em] ${icon}`} />
+      );
     }
-    return isSvg ? (
-      <svg viewBox={viewBox}>
-        <path fill="currentColor" d={icon.toString()} />
-      </svg>
-    ) : icon?.toString().length <= 4 ? (
-      <svg role="img">
-        <text
-          x="50%"
-          y="50%"
-          dy=".1em"
-          dominantBaseline="middle"
-          textAnchor="middle"
-          style={{ fontSize: SvgTextSize[icon.length] ?? "1em" }}
-        >
-          {icon}
-        </text>
-      </svg>
-    ) : (
-      <i className={`${icon}`} />
-    );
-  }, [icon, isSvg, viewBox]);
+    throw Error("Invalid icon expected string");
+  }, [icon, viewBox]);
 
   return (
     <dfn
-      {...rest}
+      data-ref="icon"
+      {...props}
       ref={ref}
       role="presentation"
-      className={classNames(
-        classes.icon,
+      className={cn(
+        "fabric-icon",
+        "inline-block",
         className,
-        "select-none overflow-hidden inline-block box-content leading-none not-italic text-center",
-        bg && getBgClass(bg),
-        color && getColorClass(color),
-        !rounded && "rounded",
-        rounded && "rounded-full",
-        animate && `animate-${animate}`,
+        "select-none overflow-hidden box-content leading-0 not-italic text-center",
+        rounded ? "rounded-full" : "rounded",
+        animate && ANIMATIONS[animate],
+        rtlFlip && "rtl:-scale-x-100",
       )}
-      onClick={onClick}
-      data-flip={rtlFlip}
-      style={styles}
-      data-clickable={!!onClick}
+      style={{
+        fontSize: size,
+        color: getColor(color),
+        backgroundColor: getColor(bg),
+      }}
     >
       {iconEl}
     </dfn>
   );
-};
+}