From efee498e46179b97d044081c913e9e6c602d50d3 Mon Sep 17 00:00:00 2001 From: "Amir.H Ebrahimi" Date: Sun, 18 Apr 2021 22:06:34 +0430 Subject: [PATCH] docs: Add documentation and logo --- README.md | 159 +++++++++++++++++++++++++++++++++++++++ doc/assets/api.svg | 27 +++++++ doc/assets/connector.svg | 27 +++++++ doc/assets/construct.svg | 27 +++++++ doc/assets/logo.svg | 1 + doc/assets/usage.svg | 27 +++++++ doc/localization/fa.md | 115 ++++++++++++++++++++++++++++ 7 files changed, 383 insertions(+) create mode 100644 README.md create mode 100644 doc/assets/api.svg create mode 100644 doc/assets/connector.svg create mode 100644 doc/assets/construct.svg create mode 100644 doc/assets/logo.svg create mode 100644 doc/assets/usage.svg create mode 100644 doc/localization/fa.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..55e47b8 --- /dev/null +++ b/README.md @@ -0,0 +1,159 @@ +

React Aptor

+

+

React API Connector

+ +--- + +[آموزش فارسی](./doc/localization/fa.md) + +Most packages are developed separately in javascript or typescript for increasing generality to make them us in all libraries and frameworks. + +Connecting third parties to react is not a routine task. on the other hand, different teams might develop these packages hence development progress can be one step behind the original or terminated at any time. +Also, wrong abstraction or bad design patterns may slow down progress or block it at every new release. + +List of some other concerns: + +- Finding dom nodes by ReactDOM-findDOMNode +- Extensively usage of memoization to improve performance or prevent extra re-renders +- Large size of the project because of duplication and all API definition in react. +- Rely on a global scope (e.g. window) for package internal setting and making it impossible to have more than one instance. + +## react-aptor + +We strived to solve them all at once + +### Small + +The unparsed project size is less than 1 kilobyte (the greatest file is 352 bytes). + +### Manageable + +Your used/defined APIs are entirely under your control. Make it possible to define a slice of APIs which you are surely going to use. + +### React-ish + +Developed with lots of care, try to be zero-anti-pattern in react. + +### Simple + +Simple with a good developer experience. + +### Typescript + +It was developed in typescript and provide the following on the fly: + +- auto-complete +- type-checking + +## How to use + +Connect your react app to any third party in three-step + +1. Define the instantiate function +2. Define the get API function +3. get connected to react by `useAptor` + +--- + +1. **First step** + > Define the instantiate function. + +```js +// construct.js +import Something from 'your-third-party' +export default function instantiate(node, params) => + new Something(node, options) +``` + +This function will return an instance of the third-party package. You have access to node (DOM-node) and params. + +> The node is passed by react-aptor as a reference to DOM that is occasionally used as a wrapper for embedding UI. +> Params are optional parameters that are passed by react-aptor and define by you. see the third step. + +2. **Second step** + +> Define the get API function. + +```js +// api.js +export default function getAPI(instance, params) { + return () => ({ + api_key: () => { + /* api defenition */ + }, + }); +} +``` + +react-aptor will pass instance and params to your `getAPI` function. The instance is your third-party instance which has been defined in the first step. + +> Params are optional parameters that are passed by react-aptor and define by you. see the third step. + +3. **Third step** + +```jsx +// connector.jsx +import useAptor from "react-aptor"; +import getAPI from "./api"; +import instantiate from "./construct"; + +const Connector = (props, ref) => { + const aptorRef = useAptor(ref, { + getAPI, + instantiate, + /* params: anything */, + }); + + return
; +}; + +export default React.forwardRef(Connector); +``` + +For the connection phase, you need to define a `forwardRef` component, grab forwarded-ref and pass that as the first argument of`useAptor` hook. As the configuration argument you need to pass defined `instantiate` (defined in the first step), `getAPI` (defined in the second step), and your custom params argument. The useAptor hook will return you a ref (`aptorRef`) with must be bound to your returned DOM node. + +The params will be then passed to your `instantiate` and `getAPI` function, as you saw in the first and second steps. +The value of params doesn't have any limitation and it can be any arbitrary type (e.g. `undefined`, `number`, `string`, `object`). You have full access to props in your component and you can define params value by props too. + +**Usage Step** + +```jsx +const Main = () => { + const ref = createRef(); + + const apiKeyHandler = () => ref.current?.api_key(); + + return ( +
+ + +
+ ); +}; +``` + +Pass `createRef` to the Connector component (made in the third step), and then you can access all of the APIs inside `ref.current` + +## Full Typescript support + +The project was developed by typescript, see samples for more info. + +## **Donation** + +🎨 Designer (**BTC**): +`bc1q9fahyct3lrdz47pjf4kfxvsyum2dm74v2hv9xl` + +💻 Developer/Maintainer (**BTC**): +`bc1qq8qq63ex7svkkjdjn5axu8angfxytvs83nlujk` + +## Samples + +### [Quilljs](https://github.com/quilljs/quill) + `typescript` + +> Quill is a free, open source WYSIWYG editor built for the modern web. +> + +### [FabricJs](http://fabricjs.com/) + +> Fabric.js is a powerful and simple. Javascript HTML5 canvas library +> diff --git a/doc/assets/api.svg b/doc/assets/api.svg new file mode 100644 index 0000000..9e9b8b9 --- /dev/null +++ b/doc/assets/api.svg @@ -0,0 +1,27 @@ +
 \ No newline at end of file diff --git a/doc/assets/connector.svg b/doc/assets/connector.svg new file mode 100644 index 0000000..edf3509 --- /dev/null +++ b/doc/assets/connector.svg @@ -0,0 +1,27 @@ +
 \ No newline at end of file diff --git a/doc/assets/construct.svg b/doc/assets/construct.svg new file mode 100644 index 0000000..01f44fc --- /dev/null +++ b/doc/assets/construct.svg @@ -0,0 +1,27 @@ +
 \ No newline at end of file diff --git a/doc/assets/logo.svg b/doc/assets/logo.svg new file mode 100644 index 0000000..2396a0a --- /dev/null +++ b/doc/assets/logo.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/doc/assets/usage.svg b/doc/assets/usage.svg new file mode 100644 index 0000000..60c2fb5 --- /dev/null +++ b/doc/assets/usage.svg @@ -0,0 +1,27 @@ +
 \ No newline at end of file diff --git a/doc/localization/fa.md b/doc/localization/fa.md new file mode 100644 index 0000000..f5a4612 --- /dev/null +++ b/doc/localization/fa.md @@ -0,0 +1,115 @@ +
+

React Aptor

+

+

متصل کننده third-partyهای مستقل به react

+ +--- + +برخی از پکیج‌ها به صورت کاملا مستقل در javascript یا typescript توسعه داده می‌شوند تا بتوان از آنها در هر framework یا library دیگری استفاده کرد. + +ارتباط این پکیچ‌ها با react کار ساده‌ای نیست (حداقل نه تا قبل از توسعه react-aptor)، از طرفی +توسعه نسخه قابل استفاده در react این پکیج‌ها گاهاً توسط تیم متفاوتی از تیم اصلی توسعه دهنده‌ی third-party صورت میگیرید و این یعنی که توسعه +نسخه react میتوانند یک مرحله عقب‌تر از نسخه اصلی باشد، یا حتی در مواقغی به صورت کامل متوقف شود. + +از طرفی کم بودن تعداد contributors روی نسخه react، انتخاب ساختار نامناسب و الگو‌های بد پیاده سازی ممکن است در اینده پیاده سازی ویژگی‌های جدید پکیج اصلی را سخت و یا حتی غیر ممکن کند. + +- استفاده از findDOMNode برای پیدا کردن المان‌ها +- استفاده بسیار زیاد از روش‌های memoization برای بهبود زمان لود و جلوگیری از re-render +- حجم زیاد این پروژه‌ها به علت تعریف دوباره اغلب ویژگی‌های پکیچ اصلی برای react +- برخی از این پکیج‌ها به صورت global در برنامه تعریف میشوند و توانایی استفاده دو نمونه از آنها در پروژه وجود ندارد. + +## react-aptor + +ما در react-aptor سعی کردیم تمام مشکلات ذکر شده در را رفع کنیم. + +### کوچک + +حجم این پروژه بسیار پایین است. کمتر از ۱ کیلو بایت (۳۵۲ بایت). + +### قابل تغییر + +دسترسی برای تعریف apiهای مورد نیاز کاملا در دست شماست. + +### react-ish + +کلیه پروژه با استاندار‌های react نوشته شده و سعی شده هیچ ضد-الگویی (anti-pattern) ای در آن استفاده نشود. + +### ساده + +استفاده از این پیکج بسیار ساده است. + +### Typescript + +پروژه با typescript توسعه داده شده و توانایی استفاده از ویژگی‌های زیر را به شما میدهد: + +- auto-complete +- type-checking + +## نحوه استفاده + +برای استفاده از این پکیج شما باید سه عمل زیر را انجام دهید +(برای استاندارد سازی پروژه ما از نام‌گاری بخصوصی استفاده کردیم.) + +1. پکیج مربوط را instantiate (معرفی) کنید +2. api خود را تعریف کنید. +3. پکیج را به وسیله react-aptor به react متصل کنید. + +## مراحل + +### مرحله اول + +> پکیج مربوط را instantiate (معرفی) بکنید + +این تابع باید نمونه پکیجی که استفاده می‌کنید را به عنوان خروجی باز گرداند. همچنین شما به عنوان ورودی‌های که react-aptor در اختیار شما میگذارد به node و پارمتر‌های تعریف خودتان نیز دسترسی دارید (params). + +> هشدار: ممکن است نیاز به new کرد نباشد، این عمل به عنوان مثال و اینکه پر کاربرد بوده استفاده شده. + +

+ +### مرحله دوم + +> api خود را تعریف کنید. + +

+ +برای این منظور شما نیاز به تعریف یک تابع به اسم `getAPI` را دارید. این تابع در حقیقت نقش `api-generator` (تولید کننده api) شما را خواهد داشت. +تابع شما دو ورودی‌اش را که instance (نمونه پکیجی که استفاده می‌کنید) و params (تمام تنظیمات مورد نیازی که خودتان تعریف کرده‌اید) باشند، را در هنگام استفاده از react-aptor دریافت خواهد کرد. + +به عنوان خروحی این تابع باید تابعی را برگردانید (return) کنید که +هیچ ورودی نمیگیرد! اما خروحی این تابع object ای که شامل api های شما به صورت key value هست خواهد‌بود. +در تعرایف api های خود میتوانید از instance و params به صورت کامل استفاده کنید. + +### مرحله سوم + +> پکیج را به وسیله react-aptor به react متصل کنید. + +

+ +برای اتصال api ها به react شما نیاز دارید که یک component +`forwardRef` تعریف کنید و ref به همراه توابع تعریف شده در مرحله ۱ و مرحله ۲ را به react-aptor تحویل بدهید. react-aptor به عنوان خروجی یک node-ref به شما باز‌میگرداند که نیاز است آن را به عنوان ref به المان dom ای که تعریف کرده‌اید متصل کنید. + +### استفاده از api هایی که تعریف شده + +

+ +برای استفاده از api ها در scope (لایه) بالاتر نیاز است از `createRef` در react استفاده کرده و ref را به `Connector` که در مرحله ۳ تعریف کردیم تحویل بدهید. به این ترتیب میتوانید به تمامی api ها از طریق `ref.current` دسترسی یابید. + +## حمایت مالی از + +🎨 طراح (**بیت‌کوین**): +`bc1q9fahyct3lrdz47pjf4kfxvsyum2dm74v2hv9xl` + +💻 توسعه‌دهنده (**بیت‌کوین**): +`bc1qq8qq63ex7svkkjdjn5axu8angfxytvs83nlujk` + +## مثال‌ها + +### `typescript` + [Quilljs](https://github.com/quilljs/quill) + +[مثال نحوه اتصال quilljs به react](https://codesandbox.io/s/react-aptor--quill-iqwcd) + +### [FabricJs](http://fabricjs.com/) + +[مثال نحوه اتصال fabric به react](https://codesandbox.io/s/react-aptor--fabric-hp50c) + +