Components / Image

components/image/.npmignore

@@ -0,0 +1 @@
+src

components/image/README.md

@@ -0,0 +1,109 @@
+# `@byndyusoft-ui/image`
+---
+
+### Installation
+
+```sh
+
+npm i @byndyusoft-ui/image
+# or
+yarn add @byndyusoft-ui/image
+```
+
+
+### Usage Image
+
+#### Basic usage
+
+```jsx
+import React from 'react';
+import Image from '@byndyusoft-ui/image';
+
+const App = () => {
+  return (
+    <Image
+      src="https://example.com/image.jpg"
+      alt="Example Image"
+    />
+  );
+};
+
+export default App;
+```
+
+#### Fallback components
+
+```jsx
+<Image
+  src="https://example.com/image.jpg"
+  alt="Example Image"
+  fallback={<div>Loading...</div>}
+  errorFallback={<div>Error loading image</div>}
+/>
+```
+
+#### Fallback src images
+
+```jsx
+<Image
+  src="https://example.com/image.jpg"
+  alt="Example Image"
+  fallbackSrc="https://example.com/fallback.jpg"
+  errorFallbackSrc="https://example.com/error.jpg"
+/>
+```
+
+#### Custom class names
+
+
+The `rootFallbackClassName` parameter adds a class to the root element that displays the `fallback` content, 
+while the `rootErrorFallbackClassName` parameter adds a class to the root element that displays the `errorFallback` content.
+
+```jsx
+ <Image
+  src="https://example.com/image.jpg"
+  alt="Example Image"
+  className="custom-image-class"
+  rootFallbackClassName="custom-root-fallback-class"
+  rootErrorFallbackClassName="custom-root-error-fallback-class"
+  fallback={<div>Loading...</div>}
+  errorFallback={<div>Error loading image</div>}
+/>
+```
+
+#### Lazy loading
+
+By default, `lazy` is set to `false`, which means the image will be loaded immediately. If `lazy` is set to `true`, 
+the image will only be loaded when it enters the viewport. This is achieved using the Intersection Observer pattern. 
+For correct lazy loading, it is also necessary to pass the `fallback` attribute, which will be placeholder as a placeholder until the image is loaded.
+
+By default, `lazy` is set to `false`, which means the image will be loaded immediately. If `lazy` is set to `true`,
+the image will only be loaded when it enters the viewport. This is achieved using the Intersection Observer pattern. 
+For correct lazy loading, it is also necessary to pass the `fallback` attribute, which will serve as a placeholder until the image is loaded.
+
+```jsx
+<Image
+  src="https://example.com/image.jpg"
+  alt="Example Image"
+  fallback={<div>Loading...</div>}
+  lazy
+/>
+```
+
+#### Settings Intersection Observer
+
+You can customize the options for the Intersection Observer using the `intersectionObserverSettings` attribute.
+
+```jsx
+<Image
+  src="https://example.com/image.jpg"
+  alt="Example Image"
+  intersectionObserverSettings={{
+    threshold: 0.5,
+    //...others options
+  }}
+/>
+```
+
+> Modify the `intersectionObserverSettings` attribute with caution, as incorrect settings can disrupt the lazy loading
+> mechanism and potentially lead to unexpected behavior.

components/image/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@byndyusoft-ui/image",
+  "version": "0.0.2",
+  "description": "Byndyusoft UI Image React Component",
+  "keywords": [
+    "byndyusoft",
+    "byndyusoft-ui",
+    "react",
+    "component",
+    "image"
+  ],
+  "author": "Gleb Fomin <gleb.fom28@gmail.com>",
+  "homepage": "https://github.com/Byndyusoft/ui/tree/master/components/image#readme",
+  "license": "Apache-2.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Byndyusoft/ui.git"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "clean": "rimraf dist",
+    "lint": "eslint src --config ../../eslint.config.js",
+    "test": "jest --config ../../jest.config.js --roots components/image/src"
+  },
+  "bugs": {
+    "url": "https://github.com/Byndyusoft/ui/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "react": ">=17",
+    "@byndyusoft-ui/use-intersection-observer": "^0.0.1"
+  }
+}

components/image/src/Image.tsx

@@ -0,0 +1,63 @@
+import React, { forwardRef, ReactElement, useImperativeHandle, useRef } from 'react';
+import { useImage } from './useImage';
+import type { IImageProps } from './Image.types';
+
+const Image = forwardRef<HTMLImageElement, IImageProps>((props, forwardedRef) => {
+    const {
+        src,
+        alt = '',
+        lazy = false,
+        fallback,
+        fallbackSrc,
+        errorFallback,
+        errorFallbackSrc,
+        className,
+        rootFallbackClassName,
+        rootErrorFallbackClassName,
+        intersectionObserverSettings,
+        ...otherProps
+    } = props;
+
+    const internalRef = useRef<HTMLImageElement | null>(null);
+
+    const { isLoading, isError, setObserverTargetRef } = useImage({
+        src,
+        lazy,
+        intersectionObserverSettings
+    });
+
+    const setRefs = (node: HTMLImageElement | null): void => {
+        internalRef.current = node;
+        setObserverTargetRef(node);
+    };
+
+    const renderImage = (imageSrc: string): JSX.Element => (
+        <img ref={setRefs} className={className} src={imageSrc} alt={alt} {...otherProps} />
+    );
+
+    const renderFallback = (content: ReactElement, rootClassName?: string): JSX.Element => (
+        <div ref={setRefs} className={rootClassName}>
+            {content}
+        </div>
+    );
+
+    useImperativeHandle(forwardedRef, () => internalRef.current as HTMLImageElement);
+
+    if (fallback && isLoading) {
+        return renderFallback(fallback, rootFallbackClassName);
+    }
+
+    if (errorFallback && isError) {
+        return renderFallback(errorFallback, rootErrorFallbackClassName);
+    }
+
+    if (fallbackSrc && isLoading) return renderImage(fallbackSrc);
+
+    if (errorFallbackSrc && isError) return renderImage(errorFallbackSrc);
+
+    return renderImage(src);
+});
+
+Image.displayName = 'Image';
+
+export default Image;

components/image/src/Image.types.ts

@@ -0,0 +1,34 @@
+import { Dispatch, ImgHTMLAttributes, ReactElement, SetStateAction } from 'react';
+import { Callback } from '@byndyusoft-ui/types';
+import { IUseIntersectionObserverOptions } from '@byndyusoft-ui/use-intersection-observer';
+
+export interface IImageProps extends ImgHTMLAttributes<HTMLImageElement> {
+    src: string;
+    className?: string;
+    rootFallbackClassName?: string;
+    rootErrorFallbackClassName?: string;
+    fallback?: ReactElement;
+    fallbackSrc?: string;
+    errorFallback?: ReactElement;
+    errorFallbackSrc?: string;
+    lazy?: boolean;
+    intersectionObserverSettings?: IUseIntersectionObserverOptions;
+}
+
+type TSetState<T> = Dispatch<SetStateAction<T>>;
+
+export interface IUseImageProps {
+    src: string;
+    lazy?: boolean;
+    intersectionObserverSettings?: IUseIntersectionObserverOptions;
+}
+
+export interface IUseImageReturn {
+    setObserverTargetRef: TSetState<Element | null>;
+    isLoading: boolean;
+    isError: boolean;
+}
+
+export type TLoadImageFunction = Callback<
+    [src: string, setIsLoading: TSetState<boolean>, setIsError: TSetState<boolean>]
+>;

components/image/src/__stories__/Image.stories.mdx

@@ -0,0 +1,44 @@
+import { Meta, Story, Canvas } from '@storybook/addon-docs';
+import { Markdown } from '@storybook/blocks';
+import Readme from '../../README.md';
+
+<Meta title="components/Image" />
+
+<Markdown>{Readme}</Markdown>
+
+# Image stories
+### Lazy fallback skeleton
+
+<Canvas>
+  <Story id="components-image--lazy-fallback-skeleton" />
+</Canvas>
+
+### Lazy fallback src
+
+<Canvas>
+  <Story id="components-image--lazy-fallback-src" />
+</Canvas>
+
+### Preload fallback skeleton
+
+<Canvas>
+  <Story id="components-image--preload-fallback-skeleton" />
+</Canvas>
+
+### Preload fallback src
+
+<Canvas>
+  <Story id="components-image--preload-fallback-src" />
+</Canvas>
+
+### Error fallback
+
+<Canvas>
+  <Story id="components-image--error-fallback" />
+</Canvas>
+
+### Error fallback src
+
+<Canvas>
+  <Story id="components-image--error-fallback-src" />
+</Canvas>

components/image/src/__stories__/Image.stories.module.css

@@ -0,0 +1,59 @@
+.wrapper {
+    margin: auto;
+    display: flex;
+    gap: 12px;
+    flex-wrap: wrap;
+    width: 612px;
+    max-height: 600px;
+}
+
+.skeleton {
+    background: linear-gradient(90deg, #f0f0f0 25%, #e0e0e0 50%, #f0f0f0 75%);
+    background-size: 200% 100%;
+    animation: shimmer 1.5s infinite;
+    border-radius: 4px;
+}
+
+.errorFallback {
+    box-sizing: border-box;
+    border: 4px solid #7a0000;
+    background: #ffa9a9;
+    color: #b30000;
+    font-size: 32px;
+    display: flex;
+    align-items: center;
+    flex-direction: column;
+    justify-content: center;
+}
+
+.refresh_btn {
+    position: fixed;
+    top: 15px;
+    left: 15px;
+    z-index: 999;
+    cursor: pointer;
+    background: yellowgreen;
+    border-radius: 50%;
+    width: 60px;
+    height: 60px;
+    border: none;
+    box-shadow: 0 0 5px 2px rgba(0, 0, 0, 0.38);
+}
+
+.refresh_btn:hover {
+    scale: 1.03;
+}
+
+.refresh_btn:active {
+    scale: 1.09;
+    opacity: 0.5;
+}
+
+@keyframes shimmer {
+    0% {
+        background-position: 200% 0;
+    }
+    100% {
+        background-position: -200% 0;
+    }
+}