diff --git a/.github/workflows/on-merge-to-main.yaml b/.github/workflows/on-merge-to-main.yaml index 046398c..1b510f0 100644 --- a/.github/workflows/on-merge-to-main.yaml +++ b/.github/workflows/on-merge-to-main.yaml @@ -6,7 +6,7 @@ on: jobs: merged: - if: github.event.pull_request.merged == true + if: github.event.pull_request.merged == true && !(startsWith(github.event.pull_request.head.ref, 'dependabot/')) runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 diff --git a/.github/workflows/on-pr-approved.yaml b/.github/workflows/on-pr-approved.yaml index 5dd6f3c..dad71a0 100644 --- a/.github/workflows/on-pr-approved.yaml +++ b/.github/workflows/on-pr-approved.yaml @@ -5,7 +5,7 @@ on: jobs: alpha: - if: github.event.review.state == 'approved' && !(startsWith(github.event.pull_request.head.ref, 'release/')) + if: github.event.review.state == 'approved' && !(startsWith(github.event.pull_request.head.ref, 'release/')) && !(startsWith(github.event.pull_request.head.ref, 'dependabot/')) runs-on: ubuntu-latest permissions: contents: write diff --git a/README.md b/README.md index d88b673..169c823 100644 --- a/README.md +++ b/README.md @@ -2,16 +2,18 @@ ## Toolkit installation and usage +For more information and examples, visit the Userfront Toolkit home page: https://userfront.com/dashboard/toolkit + To install and use the Userfront Toolkit, follow the instructions for your framework or platform: ### React -**Install:** `npm install --save @userfront/react` +**Install:** `npm install --save @userfront/toolkit` **Use:** ```js -import Userfront, { SignupForm } from "@userfront/react"; +import Userfront, { SignupForm } from "@userfront/toolkit/react"; Userfront.init("myTenantId"); @@ -20,89 +22,132 @@ export default function MyComponent() { } ``` -_or_ +### Vue + +**Install:** `npm install --save @userfront/toolkit` + +**Use:** ```js -// App.js -import { UserfrontContext } from "@userfront/react" - -export default function App() { - return ( - - - - ) -} + + + + + +``` + +### Without framework + +**Install:** `npm install --save @userfront/toolkit` + +**Use:** + +```html + + + + + + + + ``` +_or_ + +If bundling, or if you want to use the npm library rather than a script, run this on page load: + ```js -// MyComponent.js -import { SignupForm } from "@userfront/react"; +import Userfront from "@userfront/toolkit/web-components"; -export default function MyComponent() { - return ; -} +Userfront.init("myTenantId"); + +// Now Toolkit components are registered as Web Components ``` -### Vue +```html + + + +``` -**Install:** `npm install --save @userfront/vue` +## Components -**Use:** (TODO) +| React | Vue & Web Components | +| ----------------------- | --------------------------------------------- | +| `` | `` | +| `` | `` | +| `` | `` | +| `` | `` | -### Without framework +Note: when using them in plain HTML, Web Components are not self-closing and must have the full closing tag. +When using in Vue, they can be written in self-closing form: ``. + +The Vue components are `` because they are Web Components under the hood, and Web Components are required to be in kebab-case. + +### Props -**Install:** `npm install --save @userfront/html` +In React, props are `camelCase`. In Vue and Web Components, props are `kebab-case`, as required by the Web Components standard. -**Use:** (TODO) +All props are optional. + +- `tenantId` / `tenant-id`: your tenant ID, from the Userfront dashboard. If you call `Userfront.init("yourTenantId")` before using the components, it's not necessary to provide this prop. +- `compact`: if `true` and username/password is an allowed factor in your tenant's [authentication flow](https://userfront.com/dashboard/authentication), show a "Password" button. If `false`, show the username and password fields directly in the form's sign-on method selection view. + - Default: `false` +- `redirect`: controls if and where the form should redirect **after** sign-on. If `false`, the form does not redirect. If set to a path, redirects to that path. If empty, redirects [as configured in your Userfront dashboard](https://userfront.com/dashboard/paths). + - Default: `undefined` +- `redirectOnLoadIfLoggedIn` / `redirect-on-load-if-logged-in`: if `true` and the user is already logged in when they load the form, redirects per the `redirect` parameter. If `false`, do not redirect if the user is already logged in when they load the form. + - Default: `false` ## Development -## Repo structure +### Repo structure This repo holds several different libraries. - `(root)` - you are here - - `/.github/workflows` - CI/CD scripts for all libraries. - - `/packages` - npm packages - - `/toolkit-react` - the `@userfront/react` toolkit. This is the primary library at the moment - the other libraries depend on this one for the form UI and logic. - - `/.storybook` - Storybook stories for the UI components, deployed to (TODO public link) - - `/toolkit-html` - the `@userfront/html` toolkit. - - `/toolkit-vue` - the `@userfront/vue` toolkit. - - `/sites` - standalone dev/test sites for all libraries. - - `/toolkit-react` - standalone dev/test site for `@userfront/react` - - `/toolkit-html` - standalone dev/test site for `@userfront/html` - - `/toolkit-vue` - standalone dev/test site for `@userfront/vue` - - `/strings` - (TODO/FUTURE) localized strings for toolkit components - -## Development installation and setup + - `/.github/workflows` - CI/CD scripts. + - `/package` - source for the npm package + - `/site` - standalone dev/test app for all libraries. -1. Clone this repo. -2. Install the packages: +The repo is configured as an npm workspace to enable sharing of libraries and dynamically linking the package to the dev app. -- In a new terminal, `cd packages/toolkit-react` and `npm install` +### Development installation and setup -3. Install dev/test apps: +1. Clone this repo. +2. Install: -- In a new terminal, `cd sites/toolkit-react` and `npm install` +- `npm install` 4. Run dev servers: -- In the `packages/toolkit-react` terminal, `npm run dev` -- In the `sites/toolkit-react` terminal, `npm run dev` - - Find the link to the local dev site in the output. - - Dev site should hot reload on changes to the package or the site. Note that any flow must be restarted after changes - refresh the page to go back to the beginning. +- `npm run dev` + +This will run the live dev servers for both the package and the site. -5. Run unit tests: +5. Run unit test: -- In the `packages/toolkit-react` terminal, `npm run test` +- `npm run test` 6. Run Storybook: -- In the `packages/toolkit-react` terminal, `npm run storybook` +- `npm run storybook -w package` - Find the link to the local Storybook server in the output. - Storybook should hot reload on changes to the package. Each UI state has its own component, so changes should show immediately and shouldn't require reloading the page. -## Architecture +### Architecture See the `README.md` in `packages/toolkit-react` for a more detailed overview of the toolkit's architecture. diff --git a/package-lock.json b/package-lock.json index cf9d7b8..c40b6a6 100644 --- a/package-lock.json +++ b/package-lock.json @@ -18698,7 +18698,7 @@ }, "package": { "name": "@userfront/toolkit", - "version": "1.0.2", + "version": "1.0.3-alpha.0", "license": "MIT", "dependencies": { "@r2wc/react-to-web-component": "^2.0.2", @@ -19013,6 +19013,33 @@ "node": ">=12" } }, + "site/node_modules/@userfront/toolkit": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/@userfront/toolkit/-/toolkit-1.0.2.tgz", + "integrity": "sha512-z9CYlLwedxv8nXw7MXMXy206DP8bvqyN6FpuRnvgFo8MoNmI5jWXMaHN/ER3RzpMAmVo8hW77UCbK+xGFzjtEQ==", + "dependencies": { + "@r2wc/react-to-web-component": "^2.0.2", + "@react-hook/resize-observer": "^1.2.6", + "@userfront/core": "^0.6.5-beta.1", + "@xstate/react": "3.0.1", + "lodash": "^4.17.21", + "react": "^18.2.0", + "react-dom": "^18.2.0", + "react-icons": "^4.4.0", + "react-phone-input-2": "^2.15.1", + "urlon": "^3.1.0", + "xstate": "4.33.6" + } + }, + "site/node_modules/@userfront/toolkit/node_modules/xstate": { + "version": "4.33.6", + "resolved": "https://registry.npmjs.org/xstate/-/xstate-4.33.6.tgz", + "integrity": "sha512-A5R4fsVKADWogK2a43ssu8Fz1AF077SfrKP1ZNyDBD8lNa/l4zfR//Luofp5GSWehOQr36Jp0k2z7b+sH2ivyg==", + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/xstate" + } + }, "site/node_modules/@vitejs/plugin-react": { "version": "2.2.0", "resolved": "https://registry.npmjs.org/@vitejs/plugin-react/-/plugin-react-2.2.0.tgz", @@ -31262,6 +31289,31 @@ "dev": true, "optional": true }, + "@userfront/toolkit": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/@userfront/toolkit/-/toolkit-1.0.2.tgz", + "integrity": "sha512-z9CYlLwedxv8nXw7MXMXy206DP8bvqyN6FpuRnvgFo8MoNmI5jWXMaHN/ER3RzpMAmVo8hW77UCbK+xGFzjtEQ==", + "requires": { + "@r2wc/react-to-web-component": "^2.0.2", + "@react-hook/resize-observer": "^1.2.6", + "@userfront/core": "^0.6.5-beta.1", + "@xstate/react": "3.0.1", + "lodash": "^4.17.21", + "react": "^18.2.0", + "react-dom": "^18.2.0", + "react-icons": "^4.4.0", + "react-phone-input-2": "^2.15.1", + "urlon": "^3.1.0", + "xstate": "4.33.6" + }, + "dependencies": { + "xstate": { + "version": "4.33.6", + "resolved": "https://registry.npmjs.org/xstate/-/xstate-4.33.6.tgz", + "integrity": "sha512-A5R4fsVKADWogK2a43ssu8Fz1AF077SfrKP1ZNyDBD8lNa/l4zfR//Luofp5GSWehOQr36Jp0k2z7b+sH2ivyg==" + } + } + }, "@vitejs/plugin-react": { "version": "2.2.0", "resolved": "https://registry.npmjs.org/@vitejs/plugin-react/-/plugin-react-2.2.0.tgz", diff --git a/package/README.md b/package/README.md index d11e068..04f114a 100644 --- a/package/README.md +++ b/package/README.md @@ -1,44 +1,4 @@ -# Userfront Toolkit - React - -## Toolkit installation and usage - -**Install:** `npm install --save @userfront/react` - -**Use:** - -```js -import Userfront, { SignupForm } from "@userfront/react"; - -Userfront.init("myTenantId"); - -export default function MyComponent() { - return ; -} -``` - -_or_ - -```js -// App.js -import { UserfrontContext } from "@userfront/react" - -export default function App() { - return ( - - - - ) -} -``` - -```js -// MyComponent.js -import { SignupForm } from "@userfront/react"; - -export default function MyComponent() { - return ; -} -``` +# Userfront Toolkit ## Development @@ -60,6 +20,28 @@ This project uses [Vite](https://vitejs.dev/) to build the bundle, using Vite's Some parts of the project are in TypeScript `.ts/.tsx` and other parts are in JavaScript `.js/.jsx`. TypeScript is used where its features are particularly beneficial, mostly in the models that describe forms' behavior. +There are two entry points. + +One exports the forms as React components: + +```js +import Userfront, { LoginForm } from "@userfront/toolkit/react"; +``` + +The other registers the forms as Web Components, suitable for usage with most front-end frameworks or in plain JS: + +```js +import Userfront from "@userfront/toolkit/web-components"; +``` + +After import, the Web Components are registered and can be used anywhere in the app: + +```html + + + +``` + **Testing** [Vitest](https://vitest.dev/) is used for unit tests. Its interface is similar to Jest, with a few additional features. diff --git a/package/package-lock.json b/package/package-lock.json index b7e06f3..8735508 100644 --- a/package/package-lock.json +++ b/package/package-lock.json @@ -1,12 +1,12 @@ { "name": "@userfront/react", - "version": "1.0.2", + "version": "1.0.3-alpha.0", "lockfileVersion": 2, "requires": true, "packages": { "": { "name": "@userfront/react", - "version": "1.0.2", + "version": "1.0.3-alpha.0", "license": "MIT", "dependencies": { "@r2wc/react-to-web-component": "^2.0.2", diff --git a/package/package.json b/package/package.json index 927ea80..0ba4264 100644 --- a/package/package.json +++ b/package/package.json @@ -1,6 +1,6 @@ { "name": "@userfront/toolkit", - "version": "1.0.2", + "version": "1.0.3-alpha.0", "description": "Bindings and components for authentication with Userfront with React, Vue, other frameworks, and plain JS + HTML", "type": "module", "directories": {