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
uploadcare · Apr 25, 2024 · 5f2a1a2 · 5f2a1a2
1 parent 45752f1
commit 5f2a1a2
Show file tree

Hide file tree

Showing 6 changed files with 127 additions and 38 deletions.
diff --git a/packages/react-uploader/README.md b/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 `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<InstanceType<UploadCtxProvider> | null>(null);
+const Example = () => {
+    const uploaderRef = useRef < InstanceType < UploadCtxProvider > | null > (null);
 
-<FileUploaderRegular refUploadCtxProvider={uploaderRef} pubkey="YOUR_PUBLIC_KEY"/>;
+
+    <FileUploaderRegular refUploadCtxProvider={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/
diff --git a/packages/react-uploader/src/Uploader/Inline/FileUploaderInline.tsx b/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";
 
 LR.registerBlocks(LR);
 
@@ -22,19 +23,17 @@ export const FileUploaderInline: FC<TProps> = ({
   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<TProps>(props),
     [props],
   );
 
   return (
-    <React.Fragment>
-      <AdapterConfig ctx-name={CTX_NAME} {...config} />
+    <div className={className}>
+      {/* @ts-ignore */}
+      <AdapterConfig userAgentIntegration={getUserAgentIntegration(config.pubkey)} ctx-name={CTX_NAME} {...config} />
       {/* @ts-ignore */}
       <AdapterUploadCtxProvider
         ref={refUploadCtxProvider}
@@ -43,6 +42,6 @@ export const FileUploaderInline: FC<TProps> = ({
       />
 
       <AdapterFileUploaderInline ctx-name={CTX_NAME} css-src={CSS_SRC_INLINE} />
-    </React.Fragment>
+    </div>
   );
 };
diff --git a/packages/react-uploader/src/Uploader/Minimal/FileUploaderMinimal.tsx b/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";
 
 LR.registerBlocks(LR);
 
@@ -23,19 +24,17 @@ export const FileUploaderMinimal: FC<TProps> = ({
   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<TProps>(props),
     [props],
   );
 
   return (
-    <React.Fragment>
-      <AdapterConfig ctx-name={CTX_NAME} {...config} />
+    <div className={className}>
+      {/* @ts-ignore */}
+      <AdapterConfig userAgentIntegration={getUserAgentIntegration(config.pubkey)} ctx-name={CTX_NAME} {...config} />
       {/* @ts-ignore */}
       <AdapterUploadCtxProvider
         ref={refUploadCtxProvider}
@@ -46,6 +45,6 @@ export const FileUploaderMinimal: FC<TProps> = ({
         ctx-name={CTX_NAME}
         css-src={CSS_SRC_MINIMAL}
       />
-    </React.Fragment>
+    </div>
   );
 };
diff --git 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,19 +25,17 @@ export const FileUploaderRegular: FC<TProps> = ({
   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<TProps>(props),
     [props],
   );
 
   return (
-    <React.Fragment>
-      <AdapterConfig ctx-name={CTX_NAME} {...config} />
+    <div className={className}>
+      {/* @ts-ignore */}
+      <AdapterConfig userAgentIntegration={getUserAgentIntegration(config.pubkey)} ctx-name={CTX_NAME} {...config}/>
       {/* @ts-ignore */}
       <AdapterUploadCtxProvider
         ref={refUploadCtxProvider}
@@ -47,6 +46,6 @@ export const FileUploaderRegular: FC<TProps> = ({
         ctx-name={CTX_NAME}
         css-src={CSS_SRC_REGULAR}
       />
-    </React.Fragment>
+    </div>
   );
 };
diff --git 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<InstanceType<UploadCtxProvider>>;
+  refUploadCtxProvider?: Ref<InstanceType<UploadCtxProvider>>;
 };
 
 type TPropsWithEvents = Partial<TEventsSchema>;

diff --git a/packages/react-uploader/src/utils/getUserAgentIntegration.ts 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;)`;
+};