From 7cf4644f40f8db1b43bbe2816350382c2178113b Mon Sep 17 00:00:00 2001 From: Frederico Estrela Gaiva Date: Fri, 8 Dec 2023 17:29:18 +0100 Subject: [PATCH 1/5] =?UTF-8?q?docs:=20=E2=9C=8F=EF=B8=8F=20updates=20depe?= =?UTF-8?q?ndencies=20and=20docs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 57 +++++++++++++++++++++++++++++++++++++++++++++++++--- package.json | 8 ++++---- yarn.lock | 7 ++++++- 3 files changed, 64 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index a76e188..87f8b6a 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,9 @@ -# miro-websdk-react-hooks [![NPM version](https://img.shields.io/npm/v/@mirohq/websdk-types.svg)](https://www.npmjs.com/package/@mirohq/websdk-types) +# miro-websdk-react-hooks [![NPM version](https://img.shields.io/npm/v/@mirohq/websdk-react-hooks.svg)](https://www.npmjs.com/package/@mirohq/websdk-react-hooks) Collection of [React hooks](https://legacy.reactjs.org/docs/hooks-intro.html) to interact with [Miro Platform WebSDK](https://developers.miro.com/docs/miro-web-sdk-introduction). +Add a bit of :sparkles:reactivity:sparkles: to your Miro app. + ## Use it! ```bash @@ -17,10 +19,57 @@ Wrap your components with [MiroProvider](<(https://github.com/miroapp/miro-react ```tsx import { MiroProvider } from "@mirohq/websdk-react-hooks"; -const App: React.FC = ({ children }) => {children}; +const App: React.FC = ({ children }) => {children}; + +/* + You can also optional inject the global Miro WebSDK instance + + const App: React.FC = ({ children }) => {children}; +*/ ``` -Make sure you have a [Miro application](https://developers.miro.com/docs/build-your-first-hello-world-app) configured to use it: +Make sure you have a [Miro application](https://developers.miro.com/docs/build-your-first-hello-world-app) configured to use it. The hooks in this library will only work within Miro boards and in a well-configured app. + +### Isomorphic or not? + +The [Miro WebSDK](https://developers.miro.com/docs/miro-web-sdk-introduction) is **NOT** isomorphic, meaning that you cannot use it in both server and client environments. This also applies to this library, it won't work you are rendereing your React components in the server. + +### What if I am using Nextjs? + +Well, in that case, you can wrap your component in a dynamic code block that will defer the component rendering to only execute in the client-side: + +```tsx +import dynamic from "next/dynamic"; +import React from "react"; +import { useCurrentUser } from "@mirohq/websdk-react-hooks"; + +const NoSsr: React.FC = (props) => ( + {props.children} +); + +const NoSSRWrapper = dynamic(() => Promise.resolve(NoSsr), { + ssr: false, +}); + +// And in your Nextjs page + +const Component: React.FC = () => { + const { status, result, error } = useCurrentUser(); + + if (status === "success") { + return

The current user is "{result?.name}"

; + } +} + +export default function OnlyInTheClient() { + return ( + + + + ); +} + +``` ## Hooks @@ -38,8 +87,10 @@ Make sure you have a [Miro application](https://developers.miro.com/docs/build-y - [Miro Platform WebSDK](https://developers.miro.com/docs/miro-web-sdk-introduction) - [React](https://react.dev/) - [Typescript](https://www.typescriptlang.org/) +- [React Hookz Web](https://react-hookz.github.io/web/) - [Jest](https://jestjs.io/) - [React testing library](https://testing-library.com/docs/react-testing-library/intro/) +- [React Hooks Testing Library](https://github.com/testing-library/react-hooks-testing-library) ## Contributing diff --git a/package.json b/package.json index f8d7014..08215db 100644 --- a/package.json +++ b/package.json @@ -60,6 +60,8 @@ "@mirohq/websdk-types": "^2.9.10", "@testing-library/react-hooks": "^8.0.1", "@types/jest": "^29.5.10", + "@types/lodash": "^4.14.202", + "@types/react": "^18.2.41", "@typescript-eslint/eslint-plugin": "^6.4.0", "@vitejs/plugin-react": "^4.2.1", "commit-and-tag-version": "^12.0.0", @@ -86,7 +88,7 @@ "rimraf": "^5.0.5", "ts-jest": "^29.1.1", "ts-node": "^10.9.1", - "typescript": "*", + "typescript": "^5.3.3", "vite": "^5.0.7" }, "config": { @@ -101,8 +103,6 @@ ] }, "dependencies": { - "@react-hookz/web": "^23.1.0", - "@types/lodash": "^4.14.202", - "@types/react": "^18.2.41" + "@react-hookz/web": "^23.1.0" } } \ No newline at end of file diff --git a/yarn.lock b/yarn.lock index c13e0ca..66a6924 100644 --- a/yarn.lock +++ b/yarn.lock @@ -7537,11 +7537,16 @@ typedarray@^0.0.6: resolved "https://registry.yarnpkg.com/typedarray/-/typedarray-0.0.6.tgz#867ac74e3864187b1d3d47d996a78ec5c8830777" integrity sha512-/aCDEGatGvZ2BIk+HmLf4ifCJFwvKFNb9/JeZPMulfgFracn9QFcAf5GO8B/mweUjSoblS5In0cWhqpfs/5PQA== -typescript@*, "typescript@>=4.6.3 || ~5": +"typescript@>=4.6.3 || ~5": version "5.3.2" resolved "https://registry.yarnpkg.com/typescript/-/typescript-5.3.2.tgz#00d1c7c1c46928c5845c1ee8d0cc2791031d4c43" integrity sha512-6l+RyNy7oAHDfxC4FzSJcz9vnjTKxrLpDG5M2Vu4SHRVNg6xzqZp6LYSR9zjqQTu8DU/f5xwxUdADOkbrIX2gQ== +typescript@^5.3.3: + version "5.3.3" + resolved "https://registry.yarnpkg.com/typescript/-/typescript-5.3.3.tgz#b3ce6ba258e72e6305ba66f5c9b452aaee3ffe37" + integrity sha512-pXWcraxM0uxAS+tN0AG/BF2TyqmHO014Z070UsJ+pFvYuRSq8KH8DmWpnbXe0pEPDHXZV3FcAbJkijJ5oNEnWw== + uglify-js@^3.1.4: version "3.17.4" resolved "https://registry.yarnpkg.com/uglify-js/-/uglify-js-3.17.4.tgz#61678cf5fa3f5b7eb789bb345df29afb8257c22c" From ff7aeed849daf481e633792623777f1e9a59b731 Mon Sep 17 00:00:00 2001 From: Frederico Estrela Gaiva Date: Fri, 8 Dec 2023 17:46:47 +0100 Subject: [PATCH 2/5] =?UTF-8?q?docs:=20=E2=9C=8F=EF=B8=8F=20adding=20CONTR?= =?UTF-8?q?IBUTING.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CONTRIBUTING.md | 83 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 83 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e69de29..0db622a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -0,0 +1,83 @@ +# Contributing + +> This guide was heavily based on https://github.com/react-hookz/web/blob/master/CONTRIBUTING.md. Pure :sparkling_heart: awesomeness :sparkling_heart:. + +First of all, thanks for contributing to `@mirohq/websdk-react-hooks`! The collective developing and +using this library appreciates your efforts. + +If you are contributing for the first time, we recommend reading this +[First Contributions guide](https://github.com/firstcontributions/first-contributions) first. + +## Project setup + +1. Fork the main repo +2. Clone the repo to your computer (add `--depth=1` to `git clone` command to save time) +3. Install dependencies: `yarn` +4. Make sure everything builds and tests: `yarn build && yarn test` +5. Create a branch for your PR: `git checkout -b pr/my-awesome-hook` + - if you are adding a new hook, name the branch based on the hook: `useUpdateEffect` + - if your change fixes an issue, name the branch based on the issue number: `fix-12345` +6. Follow the directions below: + +> **Tip:** to keep your `main` branch pointing to the original repo's `main` (instead of your +> fork's `main`) do this: +> +> ```shell +> git remote add upstream https://github.com/miroapp/miro-react-hooks +> git fetch upstream +> git branch --set-upstream-to=upstream/main main +> ``` +> +> After running these commands you'll be able to easily pull changes from the original repository +> with +> `git pull`. + +## Development + +1. Implement the hook in the `src` folder. + - The folder should be named after your new hooks, for instance: `./src/myAwesomeHook`. + - The file with hook implementation should be named in the same way and placed inside the above created subdirectory as `./src/myAwesomeHook/myAwesomeHook.ts` + - The hook should be exported by name, not default-exported. + - If the hook has custom types in its parameters or return values, they should be exported as + well. + - Types and interfaces should **not** have prefixes like `I` or `T`. + - The hook should be developed to run specifically in the client. + - If your hook reuses other @mirohq/websdk-react-hooks/web hooks, import them as + `import { useToggle } from '../useToggle';` instead of + `import { useToggle } from '..';` + - Create an `index.ts` file within the same subdirectory and export all the hook dependencies. +2. Re-export the hook implementation and all its custom types in `src/index.ts`. +3. Fully test your hook. +4. Write docs for your hook. + - Docs should be colocated with the implementation using the same name for the markdown file, following our previous example, it should be `./src/myAwesomeHook/myAwesomeHook.md`. + For example: `src/useFirstMountState/__docs__/story.mdx`. + - Write a short example demonstrating your hook in the markdown file. +5. Add a summary of the hook and a link to the docs to `README.md`. +6. After all the above steps are done, run `yarn format` to ensure that everything is styled by + our standards and there are no linting issues. +7. `yarn new-hook myAwesomeHook` will help you to create a proper file structure for the new hook. + +## Committing + +### Commit message + +This repo uses [commit-and-tag-version](https://github.com/absolute-version/commit-and-tag-version) and +[conventional commit messages](https://conventionalcommits.org) so prefix your commits with `fix:`, +`feat:`, etc., so that your changes appear in the +[release notes](https://github.com/react-hookz/web/blob/main/CHANGELOG.md). + +Also, there is a script that helps you to properly format commit messages: + +```shell +git add . +yarn commit +``` + +The script guides you through several prompts that help you with writing a good commit message, +including many non-obvious and easy-to-forget parts. + +### Git hooks + +This project includes Git hooks that are automatically enabled when you install the dependencies. +These hooks automatically test and validate your code and commit messages before each commit. In +most cases disabling these hooks is not recommended. \ No newline at end of file From a9fc736709ea0e76948e6c6af37ed1d281508652 Mon Sep 17 00:00:00 2001 From: Frederico Estrela Gaiva Date: Fri, 8 Dec 2023 17:51:19 +0100 Subject: [PATCH 3/5] =?UTF-8?q?docs:=20=E2=9C=8F=EF=B8=8F=20fix=20minor=20?= =?UTF-8?q?mispellins=20in=20CONTRIBUTING.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CONTRIBUTING.md | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0db622a..200777f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,8 +2,7 @@ > This guide was heavily based on https://github.com/react-hookz/web/blob/master/CONTRIBUTING.md. Pure :sparkling_heart: awesomeness :sparkling_heart:. -First of all, thanks for contributing to `@mirohq/websdk-react-hooks`! The collective developing and -using this library appreciates your efforts. +Thanks for contributing to `@mirohq/websdk-react-hooks`. If you are contributing for the first time, we recommend reading this [First Contributions guide](https://github.com/firstcontributions/first-contributions) first. @@ -14,7 +13,7 @@ If you are contributing for the first time, we recommend reading this 2. Clone the repo to your computer (add `--depth=1` to `git clone` command to save time) 3. Install dependencies: `yarn` 4. Make sure everything builds and tests: `yarn build && yarn test` -5. Create a branch for your PR: `git checkout -b pr/my-awesome-hook` +5. Create a branch for your PR: `git checkout -b my-awesome-hook` - if you are adding a new hook, name the branch based on the hook: `useUpdateEffect` - if your change fixes an issue, name the branch based on the issue number: `fix-12345` 6. Follow the directions below: @@ -35,19 +34,19 @@ If you are contributing for the first time, we recommend reading this ## Development 1. Implement the hook in the `src` folder. - - The folder should be named after your new hooks, for instance: `./src/myAwesomeHook`. - - The file with hook implementation should be named in the same way and placed inside the above created subdirectory as `./src/myAwesomeHook/myAwesomeHook.ts` + - The folder should be named after your new hook, for instance: `./src/myAwesomeHook`. + - The file with hook implementation should use the same name and be placed inside the above created subdirectory as `./src/myAwesomeHook/myAwesomeHook.ts` - The hook should be exported by name, not default-exported. - If the hook has custom types in its parameters or return values, they should be exported as well. - Types and interfaces should **not** have prefixes like `I` or `T`. - The hook should be developed to run specifically in the client. - - If your hook reuses other @mirohq/websdk-react-hooks/web hooks, import them as - `import { useToggle } from '../useToggle';` instead of - `import { useToggle } from '..';` + - If your hook reuses other `@mirohq/websdk-react-hooks` hooks, import them as + `import { useMiro } from '../useMiro';` instead of + `import { useMiro } from '..';` - Create an `index.ts` file within the same subdirectory and export all the hook dependencies. -2. Re-export the hook implementation and all its custom types in `src/index.ts`. -3. Fully test your hook. +2. Re-export the hook implementation and all its custom types in `./src/index.ts`. +3. Fully test your hook, the test filename should use the same hook's name, `./src/myAwesomeHook/myAwesomeHook.text.tsx` 4. Write docs for your hook. - Docs should be colocated with the implementation using the same name for the markdown file, following our previous example, it should be `./src/myAwesomeHook/myAwesomeHook.md`. For example: `src/useFirstMountState/__docs__/story.mdx`. @@ -55,7 +54,6 @@ If you are contributing for the first time, we recommend reading this 5. Add a summary of the hook and a link to the docs to `README.md`. 6. After all the above steps are done, run `yarn format` to ensure that everything is styled by our standards and there are no linting issues. -7. `yarn new-hook myAwesomeHook` will help you to create a proper file structure for the new hook. ## Committing From 59f6423d70f632529e8f37cfcf9d78acd282ef26 Mon Sep 17 00:00:00 2001 From: Frederico Estrela Gaiva Date: Fri, 8 Dec 2023 17:52:29 +0100 Subject: [PATCH 4/5] =?UTF-8?q?docs:=20=E2=9C=8F=EF=B8=8F=20removes=20unne?= =?UTF-8?q?ded=20line=20from=20CONTRIBUTING.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CONTRIBUTING.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 200777f..35372b9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -49,8 +49,7 @@ If you are contributing for the first time, we recommend reading this 3. Fully test your hook, the test filename should use the same hook's name, `./src/myAwesomeHook/myAwesomeHook.text.tsx` 4. Write docs for your hook. - Docs should be colocated with the implementation using the same name for the markdown file, following our previous example, it should be `./src/myAwesomeHook/myAwesomeHook.md`. - For example: `src/useFirstMountState/__docs__/story.mdx`. - - Write a short example demonstrating your hook in the markdown file. + - Write a short example demonstrating your hook in that markdown file. 5. Add a summary of the hook and a link to the docs to `README.md`. 6. After all the above steps are done, run `yarn format` to ensure that everything is styled by our standards and there are no linting issues. From 24aa765c57f4526e2b7dcf25e4b1c0cf817577f0 Mon Sep 17 00:00:00 2001 From: Frederico Estrela Gaiva Date: Fri, 8 Dec 2023 17:52:57 +0100 Subject: [PATCH 5/5] chore(release): 0.0.2 --- CHANGELOG.md | 9 +++++++++ package.json | 4 ++-- 2 files changed, 11 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f223d89..324b033 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,15 @@ All notable changes to this project will be documented in this file. See [commit-and-tag-version](https://github.com/absolute-version/commit-and-tag-version) for commit guidelines. +## 0.0.2 (2023-12-08) + + +### Features + +* 🎸 introduces hook useSession ([#5](https://github.com/miroapp/miro-react-hooks/issues/5)) ([edd60c4](https://github.com/miroapp/miro-react-hooks/commit/edd60c4d0a4d76c39dff05a86d195f278becce6f)) +* 🎸 introduces useStorage hook ([#4](https://github.com/miroapp/miro-react-hooks/issues/4)) ([553f844](https://github.com/miroapp/miro-react-hooks/commit/553f844bc88a8e9cf5c881742ffe843674f97bd3)) +* 🎸 introduces useViewport ([#3](https://github.com/miroapp/miro-react-hooks/issues/3)) ([8def41f](https://github.com/miroapp/miro-react-hooks/commit/8def41ffff0c88f32543709b42545385d3391379)) + ## 0.0.1 (2023-12-08) diff --git a/package.json b/package.json index 08215db..1d655aa 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@mirohq/websdk-react-hooks", - "version": "0.0.1", + "version": "0.0.2", "description": "Collection of React Hooks wrappers for Miro WebSDK", "main": "esm/index.js", "module": "esm/index.js", @@ -105,4 +105,4 @@ "dependencies": { "@react-hookz/web": "^23.1.0" } -} \ No newline at end of file +}