diff --git a/CHANGELOG.md b/CHANGELOG.md index 57156000..c0c784b9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,10 @@ - Fixed state tax boolean validation issues - Updated Gusto embedded-api version to the latest +### Breaking changes + +Be sure to note the breaking change listed below for version 0.8.2 around component renaming and removal of the top level Flow component. + ## 0.8.2 - Refactored employee flow components structure and improved organization within Employee namespace @@ -17,6 +21,56 @@ - Fixed commission Zod schema validation issues - Fixed issue with headers not being passed properly through our API client +### Breaking changes + +> Note: We are pre alpha and are regularly iterating on the SDK as we learn more about our consumers and their needs which sometimes involves breaking changes. [Read more about our current versioning strategy here](./docs/04/01/versioning.md). + +#### Rename components to remove the "Flow" naming suffix + +The following components have been updated to remove the "Flow" naming suffix. + +| Old name | Updated name | +| ----------------------------- | ------------------------- | +| `Employee.DocumentSignerFlow` | `Employee.DocumentSigner` | +| `Company.LocationsFlow` | `Company.Locations` | +| `Company.BankAccountFlow` | `Company.BankAccount` | +| `Company.StateTaxesFlow` | `Company.StateTaxes` | +| `Company.DocumentSignerFlow` | `Company.DocumentSigner` | + +#### Removed top level Flow component and renamed flow subcomponents + +We have removed the top level `Flow` component and have migrated the flow subcomponents to `Employee` and `Company` respectively. + +| Old name | Updated name | +| --------------------------------- | ----------------------------- | +| `Flow.EmployeeOnboardingFlow` | `Employee.OnboardingFlow` | +| `Flow.EmployeeSelfOnboardingFlow` | `Employee.SelfOnboardingFlow` | + +Some examples of before/after: + +_Before_ + +```tsx +import { Flow } from '@gusto/embedded-react-sdk' + +... + + + + +``` + +_After_ + +```tsx +import { Employee } from '@gusto/embedded-react-sdk' + +... + + + +``` + ## 0.8.1 - Replaced Valibot with Zod for bundle size reduction. Also included zod as a dependency @@ -125,7 +179,9 @@ You would do the following instead:: > ``` -#### DocumentSigner has been renamed to DocumentSigner +#### DocumentSigner has been renamed to DocumentSignerFlow + +> This was actually reverted in 0.8.2. If you have DocumentSigner as the component name, you can continue to use that if you are on 0.8.2 or later. Between 0.7.0 up until 0.8.2 the naming is DocumentSignerFlow Where you would previously do @@ -136,7 +192,7 @@ Where you would previously do You should update the naming as follows: ```tsx - {}} /> + {}} /> ``` ## 0.6.0 diff --git a/docs/03/01/authentication-1.md b/docs/03/01/authentication-1.md index 918b4605..7ddbee3a 100644 --- a/docs/03/01/authentication-1.md +++ b/docs/03/01/authentication-1.md @@ -12,13 +12,13 @@ The most simple implementation is one where a partner has a backend service that ![](https://files.readme.io/161c4c0c0952486a811a18c71d959a8bd74ca4884f2fc1abe39737c988f3a05f-image.png) -The `` can receive a `baseUrl` that can be configured with the address of your backend proxy service and can also be used if necessary to pass along vendor authentication credentials. +The `` can receive a `baseUrl` that can be configured with the address of your backend proxy service and can also be used if necessary to pass along vendor authentication credentials. ```jsx react -import { GustoApiProvider } from '@gusto/embedded-react-sdk' +import { GustoProvider } from '@gusto/embedded-react-sdk' function App() { - return Your app here! + return Your app here! } export default App diff --git a/docs/03/getting-started-1.md b/docs/03/getting-started-1.md index c4d4b469..30d27f4d 100644 --- a/docs/03/getting-started-1.md +++ b/docs/03/getting-started-1.md @@ -14,13 +14,13 @@ npm i @gusto/embedded-react-sdk ## Configuring the API provider -The `GustoApiProvider` is used to configure the SDK at the application level. It must wrap the top-level component tree (typically at the root of the application) to ensure SDK components have access to the necessary configurations. +The `GustoProvider` is used to configure the SDK at the application level. It must wrap the top-level component tree (typically at the root of the application) to ensure SDK components have access to the necessary configurations. ```jsx -import { GustoApiProvider } from '@gusto/embedded-react-sdk' +import { GustoProvider } from '@gusto/embedded-react-sdk' function App() { - return ... + return ... } export default App diff --git a/docs/04/01/composition.md b/docs/04/01/composition.md index 63c15170..cf605c2f 100644 --- a/docs/04/01/composition.md +++ b/docs/04/01/composition.md @@ -11,13 +11,13 @@ import { EmployeeOnboardingFlow } from '@gusto/embedded-react-sdk'; function MyApp({ companyId }) { return( - {...}} /> - + ); } ``` @@ -33,7 +33,7 @@ import { Employee } from '@gusto/embedded-react-sdk'; function MyApp({ employeeId, startDate }) { return( - {...}} /> - + ); } ``` @@ -53,46 +53,3 @@ function MyApp({ employeeId, startDate }) { Each step of the employee onboarding flow can be imported like this in isolation and used directly as needed. (For a comprehensive list of employee onboarding components available [see the Employee Onboarding documentation here](?tab=t.ueez3pueaqpd#heading=h.ojoq455ctuev)). Because each step is available for direct use in isolation, it is also possible to rearrange steps, compose them with your own content, or [integrate them with your routing infrastructure as outlined here](?tab=t.kl25ghwrpy9i#heading=h.n2ha5hq6v67a). For example, we could place this compensation form inside of an existing page inline with our own components, or we could use this as a step in a different flow entirely. - -### Further customization - -Individual flow components can be further decomposed, modified or rearranged. Every flow component makes its individual pieces available (header, actions, content, etc). This enables developers and designers to customize the layout and order according to their needs. The following example demonstrates how to break down the `Employee.Compensation` component (from the previous section) into subcomponents, insert additional content after the header, and insert custom styles around the actions. - -```jsx -import { Employee } from '@gusto/embedded-react-sdk' - -function MyApp({ employeeId, startDate }) { - return ( - - {}}> - - {/* Custom instructional message */} -

Fill out all fields as best you can

- - - {/* Actions wrapped in custom styling */} -
- -
- - - ) -} -``` - -![](https://files.readme.io/b2108cbc99e8dda2b7e89fe95ea4b7dcc3ab18f4d96f36313a0be226ea6baed3-image.png) - -The `Employee.Compensation` component can be broken out into individual subcomponents which can be rearranged or customized as needed. These subcomponents can be set as children, and provided in any order. - -In the code sample above, we’ve provided some additional “Fill out all fields as best you can” helper text between the header and the edit form. We’ve also updated the actions to have a top border, gray background, and some more prominent actions by wrapping them in a dedicated div. diff --git a/docs/04/01/event-handling.md b/docs/04/01/event-handling.md index b46fad99..32df9619 100644 --- a/docs/04/01/event-handling.md +++ b/docs/04/01/event-handling.md @@ -37,13 +37,13 @@ const handleEvent = (eventType, data) => { function MyApp({ companyId }) { return ( - - + ) } ``` diff --git a/docs/04/01/providing-your-own-data.md b/docs/04/01/providing-your-own-data.md index 7eb8ffd1..0cb78ec1 100644 --- a/docs/04/01/providing-your-own-data.md +++ b/docs/04/01/providing-your-own-data.md @@ -18,7 +18,7 @@ function MyApp({ employeeId, startDate }) { }; return( - {...}} defaultValues={someApplicationData} /> - + ); } ``` diff --git a/docs/04/01/routing.md b/docs/04/01/routing.md index 6194fc8f..3bb9f910 100644 --- a/docs/04/01/routing.md +++ b/docs/04/01/routing.md @@ -279,13 +279,13 @@ export default function App({ companyId, employeeId }: AppProps) { employeeId, }); return ( - - + ); } diff --git a/docs/04/01/styles-and-theming.md b/docs/04/01/styles-and-theming.md index 259849bc..bc05ce65 100644 --- a/docs/04/01/styles-and-theming.md +++ b/docs/04/01/styles-and-theming.md @@ -8,7 +8,7 @@ The Gusto Embedded React SDK ships with preliminary styles for the UI components import '@gusto/embedded-react-sdk/style.css' ``` -Consumers typically apply this import at the application root where they are also setting up the `GustoApiProvider`. +Consumers typically apply this import at the application root where they are also setting up the `GustoProvider`. ### Setting up themes @@ -16,10 +16,10 @@ Themes are a collection of variables that determine how the styles applied to Re ### Where are themes set? -You can set the application theme by passing it as the `theme` prop to the `GustoApiProvider` component. +You can set the application theme by passing it as the `theme` prop to the `GustoProvider` component. ```jsx jsx -import { GustoApiProvider } from '@gusto/embedded-react-sdk' +import { GustoProvider } from '@gusto/embedded-react-sdk' import '@gusto/embedded-react-sdk/style.css' const myCustomTheme = { @@ -32,21 +32,21 @@ const myCustomTheme = { function MyApp({ children }) { return ( - {children} - + ) } ``` ### How are themes structured? -Themes are objects that contain style properties. The `GTheme` interface (viewable [in the index.d.ts file in our published code on npm](https://www.npmjs.com/package/@gusto/embedded-react-sdk?activeTab=code) or navigable if you inspect the theme property on the GustoApiProvider using an IDE) defines the shape of the object and all of the supported style properties. Here is the root object shape at a glance: +Themes are objects that contain style properties. The `GTheme` interface (viewable [in the index.d.ts file in our published code on npm](https://www.npmjs.com/package/@gusto/embedded-react-sdk?activeTab=code) or navigable if you inspect the theme property on the GustoProvider using an IDE) defines the shape of the object and all of the supported style properties. Here is the root object shape at a glance: ```typescript interface GTheme { @@ -68,10 +68,10 @@ interface GTheme { ### Applying a custom theme -You can define custom themes with your own custom variables and pass them to the GustoApiProvider via the `theme` prop. The `theme` prop actually takes a `GTheme` [deep partial](https://dev.to/perennialautodidact/adventures-in-typescript-deeppartial-2f2a), meaning you are able to selectively override only properties that you want. Observe the following: +You can define custom themes with your own custom variables and pass them to the GustoProvider via the `theme` prop. The `theme` prop actually takes a `GTheme` [deep partial](https://dev.to/perennialautodidact/adventures-in-typescript-deeppartial-2f2a), meaning you are able to selectively override only properties that you want. Observe the following: ```jsx -import { GustoApiProvider, Employee } from '@gusto/embedded-react-sdk'; +import { GustoProvider, Employee } from '@gusto/embedded-react-sdk'; import "@gusto/embedded-react-sdk/style.css"; const myCustomTheme = { @@ -96,14 +96,14 @@ const myCustomTheme = { function MyApp({ companyId }) { return( - {...}} /> - + ); } ``` @@ -121,7 +121,7 @@ In practice that means we can update all our UI components by updating the globa If we set our own theme variables for the colors and typography, it will change the look of these components. ```jsx -import { GustoApiProvider, Employee } from '@gusto/embedded-react-sdk'; +import { GustoProvider, Employee } from '@gusto/embedded-react-sdk'; import "@gusto/embedded-react-sdk/style.css"; const myCustomTheme = { @@ -156,14 +156,14 @@ const myCustomTheme = { function MyApp({ companyId }) { return( - {...}} /> - + ); } ``` @@ -175,7 +175,7 @@ The resulting UI would be: Observe how the table, badges, and button all updated based on changing the core color palette and typography. If we need further customization, we can update variables at the component level to fine tune. In the following code, we set component level overrides for button and badge: ```jsx -import { GustoApiProvider, Employee } from '@gusto/embedded-react-sdk'; +import { GustoProvider, Employee } from '@gusto/embedded-react-sdk'; import "@gusto/embedded-react-sdk/style.css"; const myCustomTheme = { @@ -221,14 +221,14 @@ const myCustomTheme = { function MyApp({ companyId }) { return( - {...}} /> - + ); } ``` @@ -254,7 +254,7 @@ You can also customize the base size used for rem calculations by updating the r For instance, if you want to set a new base size, you can do so like this: ```jsx jsx -import { GustoApiProvider, Employee } from '@gusto/embedded-react-sdk'; +import { GustoProvider, Employee } from '@gusto/embedded-react-sdk'; import "@gusto/embedded-react-sdk/style.css"; const myCustomTheme = { @@ -264,14 +264,14 @@ const myCustomTheme = { function MyApp({ companyId }) { return( - {...}} /> - + ); } ``` diff --git a/docs/04/01/translation.md b/docs/04/01/translation.md index 7b90b775..1fc1cf6e 100644 --- a/docs/04/01/translation.md +++ b/docs/04/01/translation.md @@ -6,7 +6,7 @@ We use [i18next](https://www.i18next.com/) to implement translations. If you are ### Supplying your own translations -You can use the `dictionary` prop on the `GustoApiProvider` to set translations. The top level key represents the language being used (“en” by default). Each string in the UI has a key and corresponding default text. Let’s go through an example updating the `Employee.PaymentMethod` component. +You can use the `dictionary` prop on the `GustoProvider` to set translations. The top level key represents the language being used (“en” by default). Each string in the UI has a key and corresponding default text. Let’s go through an example updating the `Employee.PaymentMethod` component. For example, take the payment details step from the Employee Onboarding Flow. Initially it renders with the following copy: @@ -21,7 +21,7 @@ import { EmployeeOnboardingFlow } from '@gusto/embedded-react-sdk'; function MyApp({ companyId }) { return( - {...}} /> - + ); } ``` diff --git a/docs/05/workflows-overview.md b/docs/05/workflows-overview.md index 33d480cf..fd9887f2 100644 --- a/docs/05/workflows-overview.md +++ b/docs/05/workflows-overview.md @@ -20,13 +20,13 @@ import { EmployeeOnboardingFlow } from '@gusto/embedded-react-sdk'; function MyApp({ companyId }) { return( - {...}} /> - + ); }