diff --git a/packages/react-uploader/README.md b/packages/react-uploader/README.md index 0284c0d..b70c181 100644 --- a/packages/react-uploader/README.md +++ b/packages/react-uploader/README.md @@ -6,44 +6,120 @@ alt=""> -Uploadcare React Uploader. Allows you to use Uploader in React applications according to React canons. - +Welcome to the Uploadcare React Uploader documentation! +This library allows you to seamlessly integrate Uploadcare file uploader into your React applications while adhering to +React principles. [![Build Status][badge-build]][build-url] [![NPM version][npm-img]][npm-url] [![GitHub release][badge-release-img]][badge-release-url] [![Uploadcare stack on StackShare][badge-stack-img]][badge-stack-url] +* [Summary about project](#summary-about-project) +* [Quick Features](#quick-features) +* [Install](#install) +* [Common](#common) + * [Usage](#usage) + * [Regular](#regular) + * [Inline](#inline) + * [Minimal](#minimal) + * [Props API](#props-api) + * [Styles](#styles) + * [File Uploader API](#file-uploader-api) + * [Events](#events) +* [Security issues](#security-issues) +* [Feedback](#feedback) + +## Summary about project + +This documentation provides guidance on how to use the Uploadcare React Uploader in your projects, along with details +about its features, installation process, usage examples, customization options, event handling, and security +considerations. + +## Quick Features + +- Seamless integration with React applications +- Three different upload options: Regular, Inline, and Minimal +- Customizable styles +- Access to File Uploader API +- Comprehensive event handling ## Install -``` +```bash npm i @uploadcare/react-uploader ``` ## Usage +The Uploadcare React Uploader offers three main components for integration. +Each component serves specific use cases and can be easily implemented into your project. + +### Regular + ```jsx -import { FileUploaderRegular } from "@uploadcare/react-uploader"; +import {FileUploaderRegular} from "@uploadcare/react-uploader"; ; ``` +### Inline + +```jsx +import {FileUploaderInline} from "@uploadcare/react-uploader"; + +; +``` + +### Minimal + +```jsx +import {FileUploaderMinimal} from "@uploadcare/react-uploader"; + +; +``` + +## Props API + +An easy way to connect React-Uploader to your project and utilize the available API props. +We provide a full set of props that are used in blocks. For review we suggest you to look at +the [documentation](uc-docs-file-uploader-options). + +## Styles + +You can customize the appearance of the React uploader using the className prop, which allows you to add custom CSS +classes to the uploader `FileUploader[Regular | Minimal | Inline]` wrapper. + +```jsx +import {FileUploaderRegular} from "@uploadcare/react-uploader"; + +; +``` + +```css +.fileUploaderWrapper lr-file-uploader-regular { +} +``` + ## File Uploader API -It is possible to get ref on UploadCtxProvider via `ref`. In this way it is possible to additional uploader management -methods. +For convenience, we provide the ability to access the File Uploader API using `refUploadCtxProvider`. +You can see what methods are available in `refUploadCtxProvider` in the [documentation][uc-docs-file-uploader-api]. +It is important to note that we now pass all InstanceType from UploadCtxProvider. ```jsx -import React, { useRef } from "react"; +import React, {useRef, useEffect} from "react"; import { FileUploaderRegular, UploadCtxProvider } from "@uploadcare/react-uploader"; -const uploaderRef = useRef | null>(null); +const Example = () => { + const uploaderRef = useRef < InstanceType < UploadCtxProvider > | null > (null); -; + + ; +} ``` ## Events @@ -57,7 +133,7 @@ The principle of converting events from blocks to React Uploader: Example: ```jsx -import { FileUploaderRegular } from "@uploadcare/react-uploader"; +import {FileUploaderRegular} from "@uploadcare/react-uploader"; = ({ refUploadCtxProvider, ...props }) => { - const CTX_NAME = useMemo( - () => ctxName ?? LR.UID.generate(), - [ctxName, LR.UID.generate], - ); + const CTX_NAME = useMemo(() => ctxName ?? LR.UID.generate(), [ctxName]); const { eventHandlers, config } = useMemo( () => getCalcPropertyOfProps(props), @@ -33,8 +31,9 @@ export const FileUploaderInline: FC = ({ ); return ( - - +
+ {/* @ts-ignore */} + {/* @ts-ignore */} = ({ /> - +
); }; diff --git a/packages/react-uploader/src/Uploader/Minimal/FileUploaderMinimal.tsx b/packages/react-uploader/src/Uploader/Minimal/FileUploaderMinimal.tsx index 58ab07e..002bcbe 100644 --- a/packages/react-uploader/src/Uploader/Minimal/FileUploaderMinimal.tsx +++ b/packages/react-uploader/src/Uploader/Minimal/FileUploaderMinimal.tsx @@ -1,4 +1,4 @@ -import React, { FC, useMemo } from "react"; +import React, { type FC, useMemo } from "react"; import * as LR from "@uploadcare/blocks"; import { customElementToReactComponent } from "@uploadcare/react-adapter"; import { AdapterConfig } from "../core/AdapterConfig"; @@ -6,6 +6,7 @@ import { AdapterUploadCtxProvider } from "../core/AdapterUploadCtxProvider"; import type { TProps } from "../types"; import { getStyleSource } from "../default"; import { getCalcPropertyOfProps } from "../../utils/getCalcPropertyOfProps"; +import { getUserAgentIntegration } from "../../utils/getUserAgentIntegration"; LR.registerBlocks(LR); @@ -23,10 +24,7 @@ export const FileUploaderMinimal: FC = ({ refUploadCtxProvider, ...props }) => { - const CTX_NAME = useMemo( - () => ctxName ?? LR.UID.generate(), - [ctxName, LR.UID.generate], - ); + const CTX_NAME = useMemo(() => ctxName ?? LR.UID.generate(), [ctxName]); const { eventHandlers, config } = useMemo( () => getCalcPropertyOfProps(props), @@ -34,8 +32,9 @@ export const FileUploaderMinimal: FC = ({ ); return ( - - +
+ {/* @ts-ignore */} + {/* @ts-ignore */} = ({ ctx-name={CTX_NAME} css-src={CSS_SRC_MINIMAL} /> - +
); }; diff --git a/packages/react-uploader/src/Uploader/Regular/FileUploaderRegular.tsx b/packages/react-uploader/src/Uploader/Regular/FileUploaderRegular.tsx index 69751ed..507a804 100644 --- a/packages/react-uploader/src/Uploader/Regular/FileUploaderRegular.tsx +++ b/packages/react-uploader/src/Uploader/Regular/FileUploaderRegular.tsx @@ -1,4 +1,4 @@ -import React, { FC, useMemo } from "react"; +import React, { type FC, useMemo } from "react"; import * as LR from "@uploadcare/blocks"; import { customElementToReactComponent } from "@uploadcare/react-adapter"; import { AdapterConfig } from "../core/AdapterConfig"; @@ -7,6 +7,7 @@ import { getStyleSource } from "../default"; import type { TProps } from "../types"; import { getCalcPropertyOfProps } from "../../utils/getCalcPropertyOfProps"; +import { getUserAgentIntegration } from "../../utils/getUserAgentIntegration"; LR.registerBlocks(LR); @@ -24,10 +25,7 @@ export const FileUploaderRegular: FC = ({ refUploadCtxProvider, ...props }) => { - const CTX_NAME = useMemo( - () => ctxName ?? LR.UID.generate(), - [ctxName, LR.UID.generate], - ); + const CTX_NAME = useMemo(() => ctxName ?? LR.UID.generate(), [ctxName]); const { eventHandlers, config } = useMemo( () => getCalcPropertyOfProps(props), @@ -35,8 +33,9 @@ export const FileUploaderRegular: FC = ({ ); return ( - - +
+ {/* @ts-ignore */} + {/* @ts-ignore */} = ({ ctx-name={CTX_NAME} css-src={CSS_SRC_REGULAR} /> - +
); }; diff --git a/packages/react-uploader/src/Uploader/types.ts b/packages/react-uploader/src/Uploader/types.ts index c931e83..35671c7 100644 --- a/packages/react-uploader/src/Uploader/types.ts +++ b/packages/react-uploader/src/Uploader/types.ts @@ -1,6 +1,6 @@ -import React from "react"; -import { - type ConfigType, +import type { Ref } from "react"; +import type { + ConfigType, UploadCtxProvider, EventMap, } from "@uploadcare/blocks"; @@ -18,7 +18,7 @@ export type TEventsSchema = { }; type TRefUploadCtxProvider = { - refUploadCtxProvider?: React.Ref>; + refUploadCtxProvider?: Ref>; }; type TPropsWithEvents = Partial; diff --git a/packages/react-uploader/src/utils/getUserAgentIntegration.ts b/packages/react-uploader/src/utils/getUserAgentIntegration.ts new file mode 100644 index 0000000..dac9b77 --- /dev/null +++ b/packages/react-uploader/src/utils/getUserAgentIntegration.ts @@ -0,0 +1,5 @@ +import { version, name } from "../../package.json"; + +export const getUserAgentIntegration = (pubkey: string) => { + return `${name}/${version}/${pubkey} (JavaScript; React;)`; +};