docs: added describe props api, styles, react-uploader-api via ref (#14)

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

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": [

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

packages/react-uploader/README.md

@@ -6,44 +6,120 @@
       alt="">
 </a>
 
-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";
 
 <FileUploaderRegular pubkey="YOUR_PUBLIC_KEY"/>;
 ```
 
+### Inline
+
+```jsx
+import {FileUploaderInline} from "@uploadcare/react-uploader";
+
+<FileUploaderInline pubkey="YOUR_PUBLIC_KEY"/>;
+```
+
+### Minimal
+
+```jsx
+import {FileUploaderMinimal} from "@uploadcare/react-uploader";
+
+<FileUploaderMinimal pubkey="YOUR_PUBLIC_KEY"/>;
+```
+
+## 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";
+
+<FileUploaderRegular className="fileUploaderWrapper" pubkey="YOUR_PUBLIC_KEY"/>;
+```
+
+```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 `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
-import React, { useRef } from "react";
+import React, {useRef, useEffect} from "react";
 import {
     FileUploaderRegular,
     UploadCtxProvider
 } from "@uploadcare/react-uploader";
 
-const uploaderRef = useRef<InstanceType<UploadCtxProvider> | null>(null);
+const Example = () => {
+    const uploaderRef = useRef < InstanceType < UploadCtxProvider > | null > (null);
 
-<FileUploaderRegular refUploadCtxProvider={uploaderRef} pubkey="YOUR_PUBLIC_KEY"/>;
+
+    <FileUploaderRegular apiRef={uploaderRef} pubkey="YOUR_PUBLIC_KEY"/>;
+}
 ```
 
 ## 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";
 
 <FileUploaderRegular
     pubkey="YOUR_PUBLIC_KEY"
@@ -109,12 +185,23 @@ request at [[email protected]][uc-email-hello].
 [uc-email-hello]: mailto:[email protected]
 
 [badge-stack-img]: https://img.shields.io/badge/tech-stack-0690fa.svg?style=flat
+
 [badge-stack-url]: https://stackshare.io/uploadcare/stacks/
+
 [badge-release-img]: https://img.shields.io/github/release/uploadcare/react-components.svg
+
 [badge-release-url]: https://github.com/uploadcare/react-components/releases
+
 [npm-img]: http://img.shields.io/npm/v/@uploadcare/react-uploader.svg
+
 [npm-url]: https://www.npmjs.com/package/@uploadcare/react-uploader
+
 [badge-build]: https://github.com/uploadcare/react-components/actions/workflows/checks.yml/badge.svg
+
 [build-url]: https://github.com/uploadcare/react-components/actions/workflows/checks.yml
 
 [uc-docs-events]: https://uploadcare.com/docs/file-uploader/events/
+
+[uc-docs-file-uploader-api]: https://uploadcare.com/docs/file-uploader/api
+
+[uc-docs-file-uploader-options]: https://uploadcare.com/docs/file-uploader/options/

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": [

packages/react-uploader/src/Uploader/Inline/FileUploaderInline.tsx

@@ -1,11 +1,12 @@
-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";
 import { AdapterUploadCtxProvider } from "../core/AdapterUploadCtxProvider";
 import type { TProps } from "../types";
 import { getStyleSource } from "../default";
 import { getCalcPropertyOfProps } from "../../utils/getCalcPropertyOfProps";
+import { getUserAgentIntegration } from "../../utils/getUserAgentIntegration.ts";
 
 LR.registerBlocks(LR);
 
@@ -19,30 +20,28 @@ const CSS_SRC_INLINE = getStyleSource("inline");
 export const FileUploaderInline: FC<TProps> = ({
   ctxName,
   className,
-  refUploadCtxProvider,
+  apiRef,
   ...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<TProps>(props),
     [props],
   );
 
   return (
-    <React.Fragment>
-      <AdapterConfig ctx-name={CTX_NAME} {...config} />
+    <div className={className}>
+      {/* @ts-ignore */}
+      <AdapterConfig userAgentIntegration={getUserAgentIntegration()} ctx-name={CTX_NAME} {...config} />
       {/* @ts-ignore */}
       <AdapterUploadCtxProvider
-        ref={refUploadCtxProvider}
+        ref={apiRef}
         ctx-name={CTX_NAME}
         {...eventHandlers}
       />
 
       <AdapterFileUploaderInline ctx-name={CTX_NAME} css-src={CSS_SRC_INLINE} />
-    </React.Fragment>
+    </div>
   );
 };

packages/react-uploader/src/Uploader/Minimal/FileUploaderMinimal.tsx

@@ -1,11 +1,12 @@
-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";
 import { AdapterUploadCtxProvider } from "../core/AdapterUploadCtxProvider";
 import type { TProps } from "../types";
 import { getStyleSource } from "../default";
 import { getCalcPropertyOfProps } from "../../utils/getCalcPropertyOfProps";
+import { getUserAgentIntegration } from "../../utils/getUserAgentIntegration.ts";
 
 LR.registerBlocks(LR);
 
@@ -20,32 +21,30 @@ const CSS_SRC_MINIMAL = getStyleSource("minimal");
 export const FileUploaderMinimal: FC<TProps> = ({
   ctxName,
   className,
-  refUploadCtxProvider,
+  apiRef,
   ...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<TProps>(props),
     [props],
   );
 
   return (
-    <React.Fragment>
-      <AdapterConfig ctx-name={CTX_NAME} {...config} />
+    <div className={className}>
+      {/* @ts-ignore */}
+      <AdapterConfig userAgentIntegration={getUserAgentIntegration()} ctx-name={CTX_NAME} {...config} />
       {/* @ts-ignore */}
       <AdapterUploadCtxProvider
-        ref={refUploadCtxProvider}
+        ref={apiRef}
         ctx-name={CTX_NAME}
         {...eventHandlers}
       />
       <AdapterFileUploaderMinimal
         ctx-name={CTX_NAME}
         css-src={CSS_SRC_MINIMAL}
       />
-    </React.Fragment>
+    </div>
   );
 };

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.ts";
 
 LR.registerBlocks(LR);
 
@@ -21,32 +22,30 @@ const CSS_SRC_REGULAR = getStyleSource("regular");
 export const FileUploaderRegular: FC<TProps> = ({
   ctxName,
   className,
-  refUploadCtxProvider,
+  apiRef,
   ...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<TProps>(props),
     [props],
   );
 
   return (
-    <React.Fragment>
-      <AdapterConfig ctx-name={CTX_NAME} {...config} />
+    <div className={className}>
+      {/* @ts-ignore */}
+      <AdapterConfig userAgentIntegration={getUserAgentIntegration()} ctx-name={CTX_NAME} {...config} />
       {/* @ts-ignore */}
       <AdapterUploadCtxProvider
-        ref={refUploadCtxProvider}
+        ref={apiRef}
         ctx-name={CTX_NAME}
         {...eventHandlers}
       />
       <AdapterFileUploaderRegular
         ctx-name={CTX_NAME}
         css-src={CSS_SRC_REGULAR}
       />
-    </React.Fragment>
+    </div>
   );
 };