From 5f2a1a2d27b0d5241c51c321a27f784fb0f68e74 Mon Sep 17 00:00:00 2001 From: Egor Didenko Date: Thu, 25 Apr 2024 22:27:36 +0300 Subject: [PATCH 1/4] docs: added describe props api, styles, react-uploader-api via ref (#14) * docs: added describe props api, styles, react-uploader-api via ref * feat: added className for wrapper * docs: added describe summary and Quick Features * feat: added userAgentIntegration --- packages/react-uploader/README.md | 107 ++++++++++++++++-- .../Uploader/Inline/FileUploaderInline.tsx | 15 ++- .../Uploader/Minimal/FileUploaderMinimal.tsx | 15 ++- .../Uploader/Regular/FileUploaderRegular.tsx | 15 ++- packages/react-uploader/src/Uploader/types.ts | 8 +- .../src/utils/getUserAgentIntegration.ts | 5 + 6 files changed, 127 insertions(+), 38 deletions(-) create mode 100644 packages/react-uploader/src/utils/getUserAgentIntegration.ts 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;)`; +}; From a840e902a659630ef34e224c639eabb538fb5625 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Thu, 25 Apr 2024 19:29:43 +0000 Subject: [PATCH 2/4] chore(release): publish - @uploadcare/react-adapter@0.2.0 - @uploadcare/react-uploader@0.2.0 --- package-lock.json | 4 ++-- packages/react-adapter/CHANGELOG.md | 10 ++++++++++ packages/react-adapter/package.json | 2 +- packages/react-uploader/CHANGELOG.md | 10 ++++++++++ packages/react-uploader/package.json | 2 +- 5 files changed, 24 insertions(+), 4 deletions(-) diff --git a/package-lock.json b/package-lock.json index 3d2570b..5dd11c1 100644 --- a/package-lock.json +++ b/package-lock.json @@ -10933,14 +10933,14 @@ }, "packages/react-adapter": { "name": "@uploadcare/react-adapter", - "version": "0.2.0-alpha.0", + "version": "0.2.0", "peerDependencies": { "@types/react": "17 || 18" } }, "packages/react-uploader": { "name": "@uploadcare/react-uploader", - "version": "0.2.0-alpha.0", + "version": "0.2.0", "license": "MIT", "dependencies": { "@uploadcare/blocks": "^0.36.1-alpha.1", diff --git a/packages/react-adapter/CHANGELOG.md b/packages/react-adapter/CHANGELOG.md index e59b1fd..b6570e2 100644 --- a/packages/react-adapter/CHANGELOG.md +++ b/packages/react-adapter/CHANGELOG.md @@ -3,6 +3,16 @@ All notable changes to this project will be documented in this file. See [Conventional Commits](https://conventionalcommits.org) for commit guidelines. +# 0.2.0 (2024-04-25) + +### Features + +- **react-uploader:** added readme.md ([#5](https://github.com/uploadcare/react-components/issues/5)) ([65c17c4](https://github.com/uploadcare/react-components/commit/65c17c43f7ef611a27def9cbd08bfbd4b2df889e)) + +### Performance Improvements + +- improve code and refactoring props ([#4](https://github.com/uploadcare/react-components/issues/4)) ([38870da](https://github.com/uploadcare/react-components/commit/38870dac59b0141299d678b352c0d2f43a245451)), closes [#3](https://github.com/uploadcare/react-components/issues/3) [#2](https://github.com/uploadcare/react-components/issues/2) [#1](https://github.com/uploadcare/react-components/issues/1) + # 0.2.0-alpha.0 (2024-04-15) ### Features diff --git a/packages/react-adapter/package.json b/packages/react-adapter/package.json index 1439388..0cddc27 100644 --- a/packages/react-adapter/package.json +++ b/packages/react-adapter/package.json @@ -1,6 +1,6 @@ { "name": "@uploadcare/react-adapter", - "version": "0.2.0-alpha.0", + "version": "0.2.0", "private": false, "type": "module", "files": [ diff --git a/packages/react-uploader/CHANGELOG.md b/packages/react-uploader/CHANGELOG.md index d41e1ea..1848fe7 100644 --- a/packages/react-uploader/CHANGELOG.md +++ b/packages/react-uploader/CHANGELOG.md @@ -3,6 +3,16 @@ All notable changes to this project will be documented in this file. See [Conventional Commits](https://conventionalcommits.org) for commit guidelines. +# 0.2.0 (2024-04-25) + +### Features + +- **react-uploader:** added readme.md ([#5](https://github.com/uploadcare/react-components/issues/5)) ([65c17c4](https://github.com/uploadcare/react-components/commit/65c17c43f7ef611a27def9cbd08bfbd4b2df889e)) + +### Performance Improvements + +- improve code and refactoring props ([#4](https://github.com/uploadcare/react-components/issues/4)) ([38870da](https://github.com/uploadcare/react-components/commit/38870dac59b0141299d678b352c0d2f43a245451)), closes [#3](https://github.com/uploadcare/react-components/issues/3) [#2](https://github.com/uploadcare/react-components/issues/2) [#1](https://github.com/uploadcare/react-components/issues/1) + # 0.2.0-alpha.0 (2024-04-15) ### Features diff --git a/packages/react-uploader/package.json b/packages/react-uploader/package.json index 30e45bd..fff0d53 100644 --- a/packages/react-uploader/package.json +++ b/packages/react-uploader/package.json @@ -1,6 +1,6 @@ { "name": "@uploadcare/react-uploader", - "version": "0.2.0-alpha.0", + "version": "0.2.0", "private": false, "type": "module", "files": [ From 71de0ff73fd3216ec0a76cbfacede5f5d9489a2b Mon Sep 17 00:00:00 2001 From: Egor Didenko Date: Mon, 29 Apr 2024 11:23:05 -0400 Subject: [PATCH 3/4] feat: updated getUserAgentIntegration --- .../src/Uploader/Inline/FileUploaderInline.tsx | 4 ++-- .../src/Uploader/Minimal/FileUploaderMinimal.tsx | 4 ++-- .../src/Uploader/Regular/FileUploaderRegular.tsx | 4 ++-- .../react-uploader/src/utils/getUserAgentIntegration.ts | 8 +++++--- 4 files changed, 11 insertions(+), 9 deletions(-) diff --git a/packages/react-uploader/src/Uploader/Inline/FileUploaderInline.tsx b/packages/react-uploader/src/Uploader/Inline/FileUploaderInline.tsx index 486be67..ee24f3b 100644 --- a/packages/react-uploader/src/Uploader/Inline/FileUploaderInline.tsx +++ b/packages/react-uploader/src/Uploader/Inline/FileUploaderInline.tsx @@ -6,7 +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"; +import { getUserAgentIntegration } from "../../utils/getUserAgentIntegration.ts"; LR.registerBlocks(LR); @@ -33,7 +33,7 @@ export const FileUploaderInline: FC = ({ return (
{/* @ts-ignore */} - + {/* @ts-ignore */} = ({ return (
{/* @ts-ignore */} - + {/* @ts-ignore */} = ({ return (
{/* @ts-ignore */} - + {/* @ts-ignore */} { - return `${name}/${version}/${pubkey} (JavaScript; React;)`; +const NAME_EXTENTION = "React-Uploader"; + +export const getUserAgentIntegration = () => { + return `${NAME_EXTENTION}/${version}`; }; From 4440e6864eb6f48e46fa2c7f21ffb5d0d986e4ae Mon Sep 17 00:00:00 2001 From: Egor Didenko Date: Mon, 29 Apr 2024 12:31:46 -0400 Subject: [PATCH 4/4] fix: renamed refUploadCtxProvider to apiRef --- packages/react-uploader/README.md | 6 +++--- .../src/Uploader/Inline/FileUploaderInline.tsx | 4 ++-- .../src/Uploader/Minimal/FileUploaderMinimal.tsx | 4 ++-- .../src/Uploader/Regular/FileUploaderRegular.tsx | 4 ++-- packages/react-uploader/src/Uploader/types.ts | 2 +- 5 files changed, 10 insertions(+), 10 deletions(-) diff --git a/packages/react-uploader/README.md b/packages/react-uploader/README.md index b70c181..f1d7d61 100644 --- a/packages/react-uploader/README.md +++ b/packages/react-uploader/README.md @@ -103,8 +103,8 @@ import {FileUploaderRegular} from "@uploadcare/react-uploader"; ## File Uploader API -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]. +For convenience, we provide the ability to access the File Uploader API using `apiRef`. +You can see what methods are available in `apiRef` in the [documentation][uc-docs-file-uploader-api]. It is important to note that we now pass all InstanceType from UploadCtxProvider. ```jsx @@ -118,7 +118,7 @@ const Example = () => { const uploaderRef = useRef < InstanceType < UploadCtxProvider > | null > (null); - ; + ; } ``` diff --git a/packages/react-uploader/src/Uploader/Inline/FileUploaderInline.tsx b/packages/react-uploader/src/Uploader/Inline/FileUploaderInline.tsx index ee24f3b..807f74c 100644 --- a/packages/react-uploader/src/Uploader/Inline/FileUploaderInline.tsx +++ b/packages/react-uploader/src/Uploader/Inline/FileUploaderInline.tsx @@ -20,7 +20,7 @@ const CSS_SRC_INLINE = getStyleSource("inline"); export const FileUploaderInline: FC = ({ ctxName, className, - refUploadCtxProvider, + apiRef, ...props }) => { const CTX_NAME = useMemo(() => ctxName ?? LR.UID.generate(), [ctxName]); @@ -36,7 +36,7 @@ export const FileUploaderInline: FC = ({ {/* @ts-ignore */} diff --git a/packages/react-uploader/src/Uploader/Minimal/FileUploaderMinimal.tsx b/packages/react-uploader/src/Uploader/Minimal/FileUploaderMinimal.tsx index 278d207..d7f1d53 100644 --- a/packages/react-uploader/src/Uploader/Minimal/FileUploaderMinimal.tsx +++ b/packages/react-uploader/src/Uploader/Minimal/FileUploaderMinimal.tsx @@ -21,7 +21,7 @@ const CSS_SRC_MINIMAL = getStyleSource("minimal"); export const FileUploaderMinimal: FC = ({ ctxName, className, - refUploadCtxProvider, + apiRef, ...props }) => { const CTX_NAME = useMemo(() => ctxName ?? LR.UID.generate(), [ctxName]); @@ -37,7 +37,7 @@ export const FileUploaderMinimal: FC = ({ {/* @ts-ignore */} diff --git a/packages/react-uploader/src/Uploader/Regular/FileUploaderRegular.tsx b/packages/react-uploader/src/Uploader/Regular/FileUploaderRegular.tsx index e12ff4e..74fae3d 100644 --- a/packages/react-uploader/src/Uploader/Regular/FileUploaderRegular.tsx +++ b/packages/react-uploader/src/Uploader/Regular/FileUploaderRegular.tsx @@ -22,7 +22,7 @@ const CSS_SRC_REGULAR = getStyleSource("regular"); export const FileUploaderRegular: FC = ({ ctxName, className, - refUploadCtxProvider, + apiRef, ...props }) => { const CTX_NAME = useMemo(() => ctxName ?? LR.UID.generate(), [ctxName]); @@ -38,7 +38,7 @@ export const FileUploaderRegular: FC = ({ {/* @ts-ignore */} diff --git a/packages/react-uploader/src/Uploader/types.ts b/packages/react-uploader/src/Uploader/types.ts index 35671c7..8f6a104 100644 --- a/packages/react-uploader/src/Uploader/types.ts +++ b/packages/react-uploader/src/Uploader/types.ts @@ -18,7 +18,7 @@ export type TEventsSchema = { }; type TRefUploadCtxProvider = { - refUploadCtxProvider?: Ref>; + apiRef?: Ref>; }; type TPropsWithEvents = Partial;