@vx-oss/heroui-v2-use-image 2.1.14-alpha.0

package/LICENSE

@@ -0,0 +1,32 @@
+SPDX-License-Identifier: MIT
+
+The MIT License (MIT)
+
+Parameters
+
+Creator / Maintainer    : Vezham Technologies Private Limited
+Original Author         : NextUI Inc
+Licensor                : Vezham Technologies Private Limited
+
+Copyright © 2025, Vezham Technologies Private Limited. All rights reserved.
+Copyright (c) 2020, NextUI Inc.
+
+---
+
+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.

package/README.md

@@ -0,0 +1,24 @@
+# @vx-oss/heroui-v2-use-image
+
+A Quick description of the component
+
+> This is an internal utility, not intended for public usage.
+
+## Installation
+
+```sh
+yarn add @vx-oss/heroui-v2-use-image
+# or
+npm i @vx-oss/heroui-v2-use-image
+```
+
+## Contribution
+
+Yes please! See the
+[contributing guidelines](https://github.com/heroui-inc/heroui/blob/master/CONTRIBUTING.md)
+for details.
+
+## License
+
+This project is licensed under the terms of the
+[MIT license](https://github.com/heroui-inc/heroui/blob/master/LICENSE).

package/dist/index.d.mts

@@ -0,0 +1,69 @@
+import { ImgHTMLAttributes } from 'react';
+
+/**
+ * Part of this code is taken from @chakra-ui/react package ❤️
+ */
+
+type NativeImageProps = ImgHTMLAttributes<HTMLImageElement>;
+interface UseImageProps {
+    /**
+     * The image `src` attribute
+     */
+    src?: string;
+    /**
+     * The image `srcset` attribute
+     */
+    srcSet?: string;
+    /**
+     * The image `sizes` attribute
+     */
+    sizes?: string;
+    /**
+     * A callback for when the image `src` has been loaded
+     */
+    onLoad?: NativeImageProps["onLoad"];
+    /**
+     * A callback for when there was an error loading the image `src`
+     */
+    onError?: NativeImageProps["onError"];
+    /**
+     * If `true`, opt out of the `fallbackSrc` logic and use as `img`
+     */
+    ignoreFallback?: boolean;
+    /**
+     * The key used to set the crossOrigin on the HTMLImageElement into which the image will be loaded.
+     * This tells the browser to request cross-origin access when trying to download the image data.
+     */
+    crossOrigin?: NativeImageProps["crossOrigin"];
+    /**
+     * Defines the `loading` attribute for the image
+     */
+    loading?: NativeImageProps["loading"];
+    /**
+     * If `true`, image load will be bypassed and the load will be handled by `as` component.
+     */
+    shouldBypassImageLoad?: boolean;
+}
+type Status = "loading" | "failed" | "pending" | "loaded";
+type FallbackStrategy = "onError" | "beforeLoadOrError";
+/**
+ * React hook that loads an image in the browser,
+ * and lets us know the `status` so we can show image
+ * fallback if it is still `pending`
+ *
+ * @returns the status of the image loading progress
+ *
+ * @example
+ *
+ * ```jsx
+ * function App(){
+ *   const status = useImage({ src: "image.png" })
+ *   return status === "loaded" ? <img src="image.png" /> : <Placeholder />
+ * }
+ * ```
+ */
+declare function useImage(props?: UseImageProps): Status;
+declare const shouldShowFallbackImage: (status: Status, fallbackStrategy: FallbackStrategy) => boolean;
+type UseImageReturn = ReturnType<typeof useImage>;
+
+export { type FallbackStrategy, type UseImageProps, type UseImageReturn, shouldShowFallbackImage, useImage };

package/dist/index.d.ts

@@ -0,0 +1,69 @@
+import { ImgHTMLAttributes } from 'react';
+
+/**
+ * Part of this code is taken from @chakra-ui/react package ❤️
+ */
+
+type NativeImageProps = ImgHTMLAttributes<HTMLImageElement>;
+interface UseImageProps {
+    /**
+     * The image `src` attribute
+     */
+    src?: string;
+    /**
+     * The image `srcset` attribute
+     */
+    srcSet?: string;
+    /**
+     * The image `sizes` attribute
+     */
+    sizes?: string;
+    /**
+     * A callback for when the image `src` has been loaded
+     */
+    onLoad?: NativeImageProps["onLoad"];
+    /**
+     * A callback for when there was an error loading the image `src`
+     */
+    onError?: NativeImageProps["onError"];
+    /**
+     * If `true`, opt out of the `fallbackSrc` logic and use as `img`
+     */
+    ignoreFallback?: boolean;
+    /**
+     * The key used to set the crossOrigin on the HTMLImageElement into which the image will be loaded.
+     * This tells the browser to request cross-origin access when trying to download the image data.
+     */
+    crossOrigin?: NativeImageProps["crossOrigin"];
+    /**
+     * Defines the `loading` attribute for the image
+     */
+    loading?: NativeImageProps["loading"];
+    /**
+     * If `true`, image load will be bypassed and the load will be handled by `as` component.
+     */
+    shouldBypassImageLoad?: boolean;
+}
+type Status = "loading" | "failed" | "pending" | "loaded";
+type FallbackStrategy = "onError" | "beforeLoadOrError";
+/**
+ * React hook that loads an image in the browser,
+ * and lets us know the `status` so we can show image
+ * fallback if it is still `pending`
+ *
+ * @returns the status of the image loading progress
+ *
+ * @example
+ *
+ * ```jsx
+ * function App(){
+ *   const status = useImage({ src: "image.png" })
+ *   return status === "loaded" ? <img src="image.png" /> : <Placeholder />
+ * }
+ * ```
+ */
+declare function useImage(props?: UseImageProps): Status;
+declare const shouldShowFallbackImage: (status: Status, fallbackStrategy: FallbackStrategy) => boolean;
+type UseImageReturn = ReturnType<typeof useImage>;
+
+export { type FallbackStrategy, type UseImageProps, type UseImageReturn, shouldShowFallbackImage, useImage };

package/dist/index.js

@@ -0,0 +1,92 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  shouldShowFallbackImage: () => shouldShowFallbackImage,
+  useImage: () => useImage
+});
+module.exports = __toCommonJS(index_exports);
+var import_react = require("react");
+var import_heroui_v2_react_utils = require("@vx-oss/heroui-v2-react-utils");
+var import_heroui_v2_use_safe_layout_effect = require("@vx-oss/heroui-v2-use-safe-layout-effect");
+function useImage(props = {}) {
+  const {
+    onLoad,
+    onError,
+    ignoreFallback,
+    src,
+    crossOrigin,
+    srcSet,
+    sizes,
+    loading,
+    shouldBypassImageLoad = false
+  } = props;
+  const isHydrated = (0, import_heroui_v2_react_utils.useIsHydrated)();
+  const imageRef = (0, import_react.useRef)(isHydrated ? new Image() : null);
+  const [status, setStatus] = (0, import_react.useState)("pending");
+  (0, import_react.useEffect)(() => {
+    if (!imageRef.current) return;
+    imageRef.current.onload = (event) => {
+      flush();
+      setStatus("loaded");
+      onLoad == null ? void 0 : onLoad(event);
+    };
+    imageRef.current.onerror = (error) => {
+      flush();
+      setStatus("failed");
+      onError == null ? void 0 : onError(error);
+    };
+  }, [imageRef.current]);
+  const flush = () => {
+    if (imageRef.current) {
+      imageRef.current.onload = null;
+      imageRef.current.onerror = null;
+      imageRef.current = null;
+    }
+  };
+  const load = (0, import_react.useCallback)(() => {
+    if (!src) return "pending";
+    if (ignoreFallback || shouldBypassImageLoad) return "loaded";
+    const img = new Image();
+    img.src = src;
+    if (crossOrigin) img.crossOrigin = crossOrigin;
+    if (srcSet) img.srcset = srcSet;
+    if (sizes) img.sizes = sizes;
+    if (loading) img.loading = loading;
+    imageRef.current = img;
+    if (img.complete && img.naturalWidth) {
+      return "loaded";
+    }
+    return "loading";
+  }, [src, crossOrigin, srcSet, sizes, onLoad, onError, loading, shouldBypassImageLoad]);
+  (0, import_heroui_v2_use_safe_layout_effect.useSafeLayoutEffect)(() => {
+    if (isHydrated) {
+      setStatus(load());
+    }
+  }, [isHydrated, load]);
+  return ignoreFallback ? "loaded" : status;
+}
+var shouldShowFallbackImage = (status, fallbackStrategy) => status !== "loaded" && fallbackStrategy === "beforeLoadOrError" || status === "failed" && fallbackStrategy === "onError";
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  shouldShowFallbackImage,
+  useImage
+});

package/dist/index.mjs

@@ -0,0 +1,66 @@
+// src/index.ts
+import { useRef, useState, useEffect, useCallback } from "react";
+import { useIsHydrated } from "@vx-oss/heroui-v2-react-utils";
+import { useSafeLayoutEffect } from "@vx-oss/heroui-v2-use-safe-layout-effect";
+function useImage(props = {}) {
+  const {
+    onLoad,
+    onError,
+    ignoreFallback,
+    src,
+    crossOrigin,
+    srcSet,
+    sizes,
+    loading,
+    shouldBypassImageLoad = false
+  } = props;
+  const isHydrated = useIsHydrated();
+  const imageRef = useRef(isHydrated ? new Image() : null);
+  const [status, setStatus] = useState("pending");
+  useEffect(() => {
+    if (!imageRef.current) return;
+    imageRef.current.onload = (event) => {
+      flush();
+      setStatus("loaded");
+      onLoad == null ? void 0 : onLoad(event);
+    };
+    imageRef.current.onerror = (error) => {
+      flush();
+      setStatus("failed");
+      onError == null ? void 0 : onError(error);
+    };
+  }, [imageRef.current]);
+  const flush = () => {
+    if (imageRef.current) {
+      imageRef.current.onload = null;
+      imageRef.current.onerror = null;
+      imageRef.current = null;
+    }
+  };
+  const load = useCallback(() => {
+    if (!src) return "pending";
+    if (ignoreFallback || shouldBypassImageLoad) return "loaded";
+    const img = new Image();
+    img.src = src;
+    if (crossOrigin) img.crossOrigin = crossOrigin;
+    if (srcSet) img.srcset = srcSet;
+    if (sizes) img.sizes = sizes;
+    if (loading) img.loading = loading;
+    imageRef.current = img;
+    if (img.complete && img.naturalWidth) {
+      return "loaded";
+    }
+    return "loading";
+  }, [src, crossOrigin, srcSet, sizes, onLoad, onError, loading, shouldBypassImageLoad]);
+  useSafeLayoutEffect(() => {
+    if (isHydrated) {
+      setStatus(load());
+    }
+  }, [isHydrated, load]);
+  return ignoreFallback ? "loaded" : status;
+}
+var shouldShowFallbackImage = (status, fallbackStrategy) => status !== "loaded" && fallbackStrategy === "beforeLoadOrError" || status === "failed" && fallbackStrategy === "onError";
+export {
+  shouldShowFallbackImage,
+  useImage
+};

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@vx-oss/heroui-v2-use-image",
+  "version": "2.1.14-alpha.0",
+  "description": "React hook for progressing image loading",
+  "keywords": [
+    "use-image"
+  ],
+  "author": "Vx OSS Devs <oss-developers@vezham.com>",
+  "homepage": "https://vezham.com",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vezham/heroui-v2.git",
+    "directory": "packages/hooks/use-image"
+  },
+  "bugs": {
+    "url": "https://github.com/vezham/heroui-v2/issues"
+  },
+  "dependencies": {
+    "@vx-oss/heroui-v2-react-utils": "2.1.15-alpha.0",
+    "@vx-oss/heroui-v2-use-safe-layout-effect": "2.1.9-alpha.0"
+  },
+  "peerDependencies": {
+    "react": ">=18 || >=19.0.0-rc.0"
+  },
+  "clean-package": "../../../clean-package.config.json",
+  "tsup": {
+    "clean": true,
+    "target": "es2019",
+    "format": [
+      "cjs",
+      "esm"
+    ]
+  },
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsup src --dts",
+    "build:fast": "tsup src",
+    "dev": "pnpm build:fast --watch",
+    "clean": "rimraf dist .turbo",
+    "typecheck": "tsc --noEmit"
+  }
+}