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

package/src/components/icon/Icon.tsx

@@ -23,31 +23,35 @@
 
 import { isString, isSvgPath } from "@react-fabric/utilities";
 import classNames from "classnames";
-import { useMemo } from "react";
+import { isValidElement, useEffect, useMemo, useState } from "react";
 import {
   type AriaProps,
   type ColorType,
   type CssProp,
+  type PaletteType,
   type RefProp,
   type SizeType,
   type TestProps,
 } from "../../types";
-import { getBgClass, getColor, getColorClass } from "../../utils";
-import classes from "./Icon.module.css";
+import { getColor } from "../../utils";
 
-export interface IconProps extends CssProp, AriaProps, RefProp, TestProps {
+export interface Props extends CssProp, AriaProps, RefProp, TestProps {
   /**
    * svg path / webfont className / 1-4 letter text
    */
-  icon: string;
+  icon: string | JSX.Element;
+  /**
+   * icon image source URL, if failed to load then shows icon
+   */
+  iconSrc?: string;
   /**
    * background color (CSS color / tailwind color)
    */
-  bg?: ColorType | string;
+  bg?: ColorType | PaletteType | string;
   /**
    * icon color (CSS color / tailwind color)
    */
-  color?: ColorType | string;
+  color?: ColorType | PaletteType | string;
   /**
    * flip icon in rtl
    */
@@ -68,12 +72,39 @@ export interface IconProps extends CssProp, AriaProps, RefProp, TestProps {
    * apply animation
    */
   animate?: "spin" | "pulse" | "bounce";
+  disabled?: boolean;
   /**
    * click handler
    */
   onClick?: React.MouseEventHandler;
 }
 
+export type IconProps =
+  | string
+  | JSX.Element
+  | Pick<
+      Props,
+      | "icon"
+      | "iconSrc"
+      | "bg"
+      | "color"
+      | "size"
+      | "rtlFlip"
+      | "viewBox"
+      | "rounded"
+      | "animate"
+    >;
+
+export const getIconProps = (props: IconProps): Props => {
+  if (typeof props === "string") {
+    return { icon: props };
+  }
+  if (isValidElement(props)) {
+    return { icon: props };
+  }
+  return props as unknown as Props;
+};
+
 const SvgTextSize = ["", ".875em", ".525em", ".35em", ".25em"];
 const SizeMap: KeyValue<string> = {
   xs: "0.625rem",
@@ -84,22 +115,56 @@ 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,
   icon,
+  iconSrc,
   bg,
   color,
   size = "",
   rtlFlip,
   animate,
   rounded,
+  disabled,
   viewBox = "0 0 24 24",
   className,
   onClick,
   ...rest
-}: IconProps) => {
+}: Props) => {
+  const [imageFailed, setImageFailed] = useState(false);
+
+  useEffect(() => {
+    setImageFailed(false);
+  }, [iconSrc]);
+
   /** ***************** style map *******************/
   const styles = useMemo(() => {
     const s: KeyValue = {};
@@ -125,6 +190,7 @@ export const Icon = ({
 
   /** ***************** render icon *******************/
   const iconEl = useMemo(() => {
+    if (isValidElement(icon)) return icon;
     if (!isString(icon)) {
       throw Error("Invalid icon expected string");
     }
@@ -140,7 +206,7 @@ export const Icon = ({
           dy=".1em"
           dominantBaseline="middle"
           textAnchor="middle"
-          style={{ fontSize: SvgTextSize[icon.length] ?? "1em" }}
+          style={{ fontSize: SvgTextSize[icon.length] }}
         >
           {icon}
         </text>
@@ -152,25 +218,37 @@ export const Icon = ({
 
   return (
     <dfn
-      {...rest}
+      data-ref="icon"
       ref={ref}
+      {...rest}
       role="presentation"
       className={classNames(
-        classes.icon,
-        className,
-        "select-none overflow-hidden inline-block box-content leading-none not-italic text-center",
-        bg && getBgClass(bg),
-        color && getColorClass(color),
+        "fabric-icon",
+        "select-none overflow-hidden box-content leading-none not-italic text-center",
         !rounded && "rounded",
         rounded && "rounded-full",
         animate && `animate-${animate}`,
+        !!onClick && disabled && "opacity-30 pointer-events-none",
+        className,
       )}
-      onClick={onClick}
+      onClick={(e) => {
+        onClick && e.stopPropagation();
+        onClick && e.preventDefault();
+        onClick?.(e);
+      }}
       data-flip={rtlFlip}
       style={styles}
       data-clickable={!!onClick}
+      data-inner-clickable={!!onClick}
     >
-      {iconEl}
+      {iconSrc && !imageFailed && (
+        <img
+          src={iconSrc}
+          alt="fallback icon"
+          onError={() => setImageFailed(true)}
+        />
+      )}
+      {(!iconSrc || imageFailed) && iconEl}
     </dfn>
   );
 };

package/src/components/index.ts

@@ -26,8 +26,8 @@ export {
   AnimationBars,
   AnimationIndicator,
   AnimationSpinner,
-  Skeleton,
   Loading,
+  Skeleton,
 } from "./animations/Animations";
 export { Avatar } from "./avatar/Avatar";
 export { AvatarGroup } from "./avatar/AvatarGroup";
@@ -40,13 +40,14 @@ export { ToggleButtonGroup } from "./button/ToggleButtonGroup";
 export { Callout } from "./callout/Callout";
 export { Card } from "./card/Card";
 export { CardCover } from "./card/CardCover";
+export { FlipContent, type FlipContentRef } from "./card/FlipContent";
 export { Chip } from "./chip/Chip";
 export { Collapsable } from "./collapsable/Collapsable";
 export { Divider } from "./divider/Divider";
 export { Dropdown, DropdownDismiss } from "./dropdown/Dropdown";
 export { DropdownTool } from "./dropdown/DropdownTool";
 export { EmptyContent } from "./empty/EmptyContent";
-export { Icon } from "./icon/Icon";
+export { Icon, getIconProps } from "./icon/Icon";
 export { Image, Video } from "./media/Media";
 export { ContextMenu } from "./menu/ContextMenu";
 export { Menu } from "./menu/Menu";

package/src/components/media/Media.tsx

@@ -23,11 +23,11 @@
 
 import { getImageColorset } from "@react-fabric/utilities";
 import classNames from "classnames";
-import { useMemo, useRef, useState } from "react";
+import { Fragment, useEffect, useRef, useState } from "react";
 import { type AriaProps, type CssProp, type TestProps } from "../../types";
 import { CoreIcons } from "../../types/icons";
 import { Button } from "../button/Button";
-import classes from "./Media.module.css";
+import { Icon } from "../icon/Icon";
 
 export interface BaseProps extends CssProp, TestProps, AriaProps {
   /**
@@ -44,6 +44,12 @@ export interface BaseProps extends CssProp, TestProps, AriaProps {
   fit?: "cover" | "contain" | "fill";
 }
 
+const cover = {
+  fill: "object-fill",
+  cover: "object-cover",
+  contain: "object-contain",
+};
+
 export interface ImageProps extends BaseProps {
   /**
    * image alt text
@@ -65,6 +71,41 @@ export interface VideoProps extends BaseProps {
   playOnHover?: boolean;
 }
 
+const loadIndicator = (
+  <div
+    className={classNames(
+      "fabric-mediaPlaceholder",
+      "absolute z-1 top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 text-4xl text-gray animate-pulse",
+    )}
+  >
+    ●●●
+  </div>
+);
+
+/**
+ * Component for displaying images with optional reel decoration.
+ * A versatile media component that supports images and videos with various display options.
+ * It can display images with a reel decoration, handle loading states, and show error icons if the media fails to load.
+ * This component is useful for displaying images in a visually appealing way, with support for lazy loading and error handling.
+ * It automatically adjusts the display based on the provided fit property, allowing for different styles such as cover, contain, or fill.
+ *
+ * @param {ImageProps | VideoProps} props - The properties for the Media component.
+ * @returns {JSX.Element} The rendered Media component.
+ *
+ * @example
+ * ```jsx
+ * <Image
+ *   src="image.jpg"
+ *   alt="Example Image"
+ *   reel={true}
+ *   fit="cover"
+ *   className="custom-class"
+ * />
+ * // Renders an image with reel decoration, cover fit, and a custom class name.
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/docs/core-components-media--docs} for more details.
+ */
 export const Image = ({
   src,
   alt,
@@ -74,51 +115,84 @@ export const Image = ({
   ...aria
 }: ImageProps) => {
   const [colorSet, setColorSet] = useState("light");
-  const loadIndicator = useMemo(
-    () => (
-      <div
-        className={classNames(
-          classes.mediaPlaceholder,
-          "absolute z-1 top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 text-4xl text-gray animate-pulse",
-        )}
-      >
-        ●●●
-      </div>
-    ),
-    [src],
-  );
+  const [loaded, setLoaded] = useState(false);
+  const [errored, setErrored] = useState(false);
+  useEffect(() => {
+    setLoaded(false);
+    setErrored(false);
+  }, [src]);
   return (
     <div
       data-ref="image"
       className={classNames(
-        classes.mediaContainer,
-        "relative overflow-hidden bg-gray inline-block",
-        reel && classes.mediaReel,
+        "fabric-mediaContainer",
+        "relative overflow-hidden inline-block",
+        reel && "fabric-mediaReel",
         className,
       )}
       data-colorset={colorSet}
       {...aria}
     >
-      {loadIndicator}
-      <img
-        alt={alt ?? src}
-        src={src}
-        loading="lazy"
-        crossOrigin="anonymous"
-        className={classNames(
-          classes.media,
-          "pointer-events-none w-full h-full",
-          fit && `object-${fit}`,
-        )}
-        onLoad={(e) => {
-          e.currentTarget.previousElementSibling?.remove();
-          setColorSet(getImageColorset(e.currentTarget));
-        }}
-      />
+      {!loaded && !errored && loadIndicator}
+      {!errored && (
+        <img
+          alt={alt ?? src}
+          src={src}
+          loading="lazy"
+          crossOrigin="anonymous"
+          className={classNames(
+            "fabric-media",
+            "pointer-events-none w-full h-full",
+            cover[fit],
+          )}
+          onLoad={(e) => {
+            setLoaded(true);
+            setColorSet(getImageColorset(e.currentTarget));
+          }}
+          onError={() => setErrored(true)}
+        />
+      )}
+      {errored && (
+        <Icon
+          size="2rem"
+          className="absolute text-tint-300 top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2"
+          icon={CoreIcons.mediaImageBroken}
+        />
+      )}
     </div>
   );
 };
 
+/**
+ * Component for displaying videos with optional controls and reel decoration.
+ * A versatile video component that supports autoplay, hover play, and various display options.
+ * It can display videos with a reel decoration, handle loading states, and show error icons if the video fails to load.
+ * This component is useful for displaying videos in a visually appealing way, with support for controls, autoplay, and error handling.
+ * It automatically adjusts the display based on the provided fit property, allowing for different styles such as cover, contain, or fill.
+ * It also includes controls for play/pause and volume, enhancing user interaction with the video content.
+ * This component is ideal for media-rich applications where video content needs to be displayed with user-friendly controls and visual effects.
+ * It supports features like autoplay, play on hover, and custom fit options for the video display.
+ * It also includes a reel decoration for a more engaging visual presentation.
+ *
+ * @param {VideoProps} props - The properties for the Video component.
+ * @returns {JSX.Element} The rendered Video component.
+ *
+ * @example
+ * ```jsx
+ * <Video
+ *   src="video.mp4"
+ *   poster="poster.jpg"
+ *   reel={true}
+ *   autoPlay={true}
+ *   playOnHover={true}
+ *   fit="cover"
+ *   className="custom-class"
+ * />
+ * // Renders a video with reel decoration, autoplay, play on hover, cover fit, and a custom class name.
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/docs/core-components-video--docs} for more details.
+ */
 export const Video = ({
   src,
   poster,
@@ -130,17 +204,27 @@ export const Video = ({
   ...aria
 }: VideoProps) => {
   const videoRef = useRef<HTMLVideoElement>(null);
+  const [loaded, setLoaded] = useState(false);
+  const [errored, setErrored] = useState(false);
+  useEffect(() => {
+    setLoaded(false);
+    setErrored(false);
+  }, [src]);
 
   const [state, setState] = useState(true);
   const [volume, setVolume] = useState(false);
 
+  useEffect(() => {
+    setErrored(false);
+  }, [src]);
+
   return (
     <div
       data-ref="video"
       className={classNames(
-        classes.mediaContainer,
-        "relative overflow-hidden bg-gray inline-block",
-        reel && classes.mediaReel,
+        "fabric-mediaContainer",
+        "relative overflow-hidden inline-block",
+        reel && "fabric-mediaReel",
         className,
       )}
       onMouseEnter={() => {
@@ -151,74 +235,79 @@ export const Video = ({
       }}
       {...aria}
     >
-      <div
-        className={classNames(
-          classes.mediaPlaceholder,
-          "absolute z-1 top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 text-5xl animate-pulse",
-        )}
-      >
-        ●●●
-      </div>
-      <video
-        loop
-        ref={videoRef}
-        controls={false}
-        poster={poster}
-        autoPlay={autoPlay}
-        className={classNames(
-          classes.media,
-          "pointer-events-none w-full h-full",
-          fit && `object-${fit}`,
-        )}
-        onPlay={() => setState(true)}
-        onPause={() => setState(false)}
-        onVolumeChange={(e) => setVolume(!!e.currentTarget.volume)}
-        onLoadedData={(e) => {
-          e.currentTarget.volume = 0;
-          e.currentTarget.previousElementSibling?.remove();
-        }}
-      >
-        <source src={src} />
-        <track kind="captions" />
-      </video>
-      <div
-        data-inner-clickable
-        className={classNames(
-          classes.mediaControls,
-          "absolute bottom-6 end-6 rounded-full flex flex-col",
-        )}
-      >
-        <Button
-          rounded
-          variant="link"
-          className={classes.mediaControlPlaceholder}
-          icon={CoreIcons.ellipsis}
-          aria-label="controls"
-        />
-        <Button
-          rounded
-          variant="link"
-          aria-label="controls"
-          className={classes.mediaControlAction}
-          onClick={() => {
-            videoRef.current &&
-              (videoRef.current.volume = videoRef.current.volume ? 0 : 1);
-          }}
-          icon={volume ? CoreIcons.volumeOn : CoreIcons.volumeOff}
-        />
-        <Button
-          rounded
-          variant="link"
-          aria-label="controls"
-          className={classes.mediaControlAction}
-          onClick={() => {
-            videoRef.current?.paused
-              ? videoRef.current?.play()
-              : videoRef.current?.pause();
-          }}
-          icon={state ? CoreIcons.pause : CoreIcons.play}
+      {!loaded && !errored && loadIndicator}
+      {!errored && (
+        <Fragment>
+          <video
+            loop
+            ref={videoRef}
+            controls={false}
+            poster={poster}
+            autoPlay={autoPlay}
+            className={classNames(
+              "fabric-media",
+              "pointer-events-none w-full h-full",
+              fit && `object-${fit}`,
+            )}
+            onPlay={() => setState(true)}
+            onPause={() => setState(false)}
+            onVolumeChange={(e) => setVolume(!!e.currentTarget.volume)}
+            onLoadedData={(e) => {
+              e.currentTarget.volume = 0;
+              setLoaded(true);
+            }}
+            onError={() => setErrored(true)}
+          >
+            <source src={src} />
+            <track kind="captions" />
+          </video>
+          <div
+            data-inner-clickable
+            className={classNames(
+              "fabric-mediaControls",
+              "absolute bottom-6 end-6 rounded-full flex flex-col",
+            )}
+          >
+            <Button
+              rounded
+              variant="link"
+              className={"fabric-mediaControlPlaceholder"}
+              icon={CoreIcons.ellipsis}
+              aria-label="controls"
+            />
+            <Button
+              rounded
+              variant="link"
+              aria-label="controls"
+              className={"fabric-mediaControlAction"}
+              onClick={() => {
+                videoRef.current &&
+                  (videoRef.current.volume = videoRef.current.volume ? 0 : 1);
+              }}
+              icon={volume ? CoreIcons.volumeOn : CoreIcons.volumeOff}
+            />
+            <Button
+              rounded
+              variant="link"
+              aria-label="controls"
+              className={"fabric-mediaControlAction"}
+              onClick={() => {
+                videoRef.current?.paused
+                  ? videoRef.current?.play()
+                  : videoRef.current?.pause();
+              }}
+              icon={state ? CoreIcons.pause : CoreIcons.play}
+            />
+          </div>
+        </Fragment>
+      )}
+      {errored && (
+        <Icon
+          size="2rem"
+          className="absolute text-tint-300 top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2"
+          icon={CoreIcons.mediaVideoBroken}
         />
-      </div>
+      )}
     </div>
   );
 };

package/src/components/menu/ContextMenu.tsx

@@ -42,6 +42,25 @@ export interface ContextMenuProps extends ChildrenProp {
   disabled?: boolean;
 }
 
+/**
+ * A component that provides a context menu that appears on right-click.
+ * It uses the Floating UI library to manage the positioning and interactions of the menu.
+ * This component is useful for creating custom context menus that can be triggered by right-clicking on elements.
+ *
+ * @param {ContextMenuProps} props - The properties for the ContextMenu component.
+ * @returns {JSX.Element} The rendered ContextMenu component.
+ *
+ * @example
+ * ```jsx
+ * <ContextMenu
+ *   menu={<Menu items={[{ label: "Option 1" }, { label: "Option 2" }]} />}
+ * >
+ *   <div className="context-menu-target">Right-click me!</div>
+ * </ContextMenu>
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/docs/core-components-menu--docs}
+ */
 export const ContextMenu = ({ children, menu, disabled }: ContextMenuProps) => {
   const [isOpen, setIsOpen] = useState(false);
   const nodeId = useFloatingNodeId();