@wise/dynamic-flow-client-internal 0.1.0

package/README.md

@@ -0,0 +1,214 @@
+# Wise Dynamic Flow Web Client
+
+This is the Wise Dynamic Flow web client. It provides a simple way to integrate a Dynamic Flow into your Wise web app.
+
+⚡ Access the latest deployed version of the [Dynamic Flow Playground](https://main--641de2ace0e1566a6a450fad.chromatic.com).
+
+## Integration
+
+1. Install `@wise/dynamic-flow-client-internal`.
+
+```
+# yarn
+yarn add @wise/dynamic-flow-client-internal
+
+# npm
+npm install @wise/dynamic-flow-client-internal
+
+# pnpm
+pnpm install @wise/dynamic-flow-client-internal
+```
+
+2. Install required peer dependencies (if not already installed). Please refer to setup instructions for `@transferwise/components` and `@transferwise/neptune-css` if installing up for the first time.
+
+```
+# yarn
+yarn add prop-types react react-dom react-intl
+yarn add @transferwise/components @transferwise/formatting @transferwise/icons @transferwise/neptune-css @transferwise/neptune-validation
+
+# npm
+npm install prop-types react react-dom react-intl
+npm install @transferwise/components @transferwise/formatting @transferwise/icons @transferwise/neptune-css @transferwise/neptune-validation
+
+# pnpm
+pnpm install prop-types react react-dom react-intl
+pnpm install @transferwise/components @transferwise/formatting @transferwise/icons @transferwise/neptune-css @transferwise/neptune-validation
+```
+
+**Note:** Keep in mind that some of these dependencies have their own peer dependencies. Don't forget to install those, for instance: `@transferwise/components` needs `@wise/art` and `@wise/components-theming`.
+
+```js
+// Should be imported once in your application
+import '@wise/dynamic-flow-client-internal/build/main.css';
+```
+
+The `DynamicFlow` component must be wraped in a Neptune `Provider` to support localisation, a `ThemeProvider` to provide theming, and a `SnackbarProvider` to ensure snackbars display correctly. Translations should be imported from both components and dynamic flows, merged, and passed to the `Provider` component (as below).
+
+```js
+import {
+  Provider,
+  SnackbarProvider,
+  translations as componentTranslations,
+  getLangFromLocale,
+  DEFAULT_LANG,
+} from '@transferwise/components';
+import {
+  DynamicFlow,
+  translations as dynamicFlowsTranslations,
+} from '@wise/dynamic-flow-client-internal/';
+
+const lang = getLangFromLocale(locale) || DEFAULT_LANG;
+const i18n = {
+  locale,
+  messages: {
+    ...componentTranslations[lang],
+    ...dynamicFlowsTranslations[lang],
+  },
+};
+
+return (
+  <Provider i18n={i18n}>
+    <ThemeProvider theme={theme}>
+      <SnackbarProvider>
+        <DynamicFlow {...props} />
+      </SnackbarProvider>
+    </ThemeProvider>
+  </Provider>
+);
+```
+
+## Configuring your Flow
+
+DF can be initialised with `initialAction` (recommended) or with an `initialStep`.
+
+```tsx
+<DynamicFlow
+  initialAction={{ method: 'GET', url: '/my-amazing-new-flow' }}
+  fetcher={(...args) => fetch(...args)}
+  onComplete={(result) => {
+    console.log('Flow exited with', result);
+  }}
+  onError={(error, statusCode) => {
+    console.error('Flow Error:', error, 'status code', statusCode);
+  }}
+/>
+```
+
+### When to use `initialStep` instead of `initialAction`
+
+In some cases you may want to obtain the initial step yourself, and then pass it to DF component. In these cases you don't provide a `initialAction` since the next steps will result from interactions in the provided `initialStep`:
+
+```tsx
+<DynamicFlow
+  initialStep={someInitialStep}
+  fetcher={...}
+  onComplete={...}
+  onError={...}
+/>
+```
+
+### The `fetcher` function prop
+
+You must pass a fetcher function. This can be `window.fetch` itself or some wrapper function where you inject authorisation headers and anything else you many need.
+
+You can take advantage of the `makeFetcher` utility function. This function takes a `baseUrl` and `additionalHeaders` arguments. The `baseUrl` will be prefixed to any relative request URLs. Absolute URLs will not be altered. The `additionalHeaders` parameter can be used to add any request headers you need in all requests, such as `{ 'X-Access-Token': 'Tr4n5f3rw153' }`:
+
+```tsx
+import { makeFetcher, DynamicFlow } from '@wise/dynamic-flow-client';
+
+const myFetcher = makeFetcher('/my-base-url', { 'X-Access-Token': 'Tr4n5f3rw153' });
+
+...
+
+<DynamicFlow
+  initialAction={{ method: 'GET', url: '/my-amazing-new-flow' }}
+  fetcher={myFetcher}
+  onComplete={...}
+  onError={...}
+/>
+```
+
+#### Custom `fetcher` functions
+
+If you want to write your own fetcher function (or if you're writing mocks), it's important that you return proper `Response` objects, and that you **do not throw**. Errors should result in a response with an error status code and potentially a body with an error message. For example:
+
+```tsx
+const mockFetcher = (input, init) => {
+  switch (input) {
+    case '/standard':
+      return Promise.resolve(new Response(init.body));
+    case '/exit':
+      return Promise.resolve(new Response(init.body, { headers: { 'x-df-exit': true } }));
+    case '/error':
+    default:
+      return Promise.resolve(new Response('An error has occurred.', { status: 500 }));
+  }
+};
+```
+Also, please make sure your mocks return a new `Response` instace every time. This is because responses are mutated when we parse their body, and they cannot be parsed a second time.
+
+```ts
+const initialResponse = new Response(JSON.stringify(initialStep));
+// ❌ wrong - the same instance is returned on each request
+const mockFetcher = (input, init) => Promise.resolve(initialResponse);
+```
+
+```ts
+// ✅ correct - a new instance is returned on each request
+const mockFetcher = (input, init) => Promise.resolve(new Response(JSON.stringify(initialStep)));
+```
+
+### Telemetry
+
+The `DynamicFlow` component accepts two optional props: `onEvent` and `onLog` which can be used to track and log.
+
+In the example below we send tracking events to Mixpanel and logging events to Rollbar.
+
+```tsx
+<DynamicFlow
+  onEvent={(event, props) => mixpanel.track(event, props)}
+  onLog={(level, message, extra) => Rollbar[level](message, extra)}
+/>
+```
+
+Alternatively, you can log to the browser console:
+
+```ts
+onEvent={(event, props) => console.log(event, props)}
+onLog={(level, message, extra) => {
+  const levelToConsole = {
+    critical: console.error,
+    error: console.error,
+    warning: console.warn,
+    info: console.info,
+    debug: console.log,
+  } as const;
+  levelToConsole[level](message, extra);
+}}
+```
+
+### Loader configuration
+
+By default, DF will display a loading animation (The `Loader` component from Neptune) when the first step is loading. It will not display it during refresh-on-change or while submitting forms.
+
+You can change the defaults by passing a `loaderConfig` prop:
+
+```ts
+type LoaderConfig = {
+  size?: `xs | sm | md | lg | xl`;
+  initial?: boolean;
+  submission?: boolean;
+};
+```
+
+| property     | type    | notes                                                                          | default |
+| ------------ | ------- | ------------------------------------------------------------------------------ | ------- |
+| `size`       | string  | The size of the Loader component.                                              | `xl`    |
+| `initial`    | boolean | Whether or not to display the Loader component while loading the initial step. | true    |
+| `submission` | boolean | Whether or not to display the Loader component during form submissions.        | false   |
+
+
+## Contributing
+
+We love contributions! Check out `CONTRIBUTING.md` for more information.
+

package/package.json

@@ -0,0 +1,99 @@
+{
+  "name": "@wise/dynamic-flow-client-internal",
+  "version": "0.1.0",
+  "description": "Dynamic Flow web client for Wise",
+  "main": "./build/index.js",
+  "types": "./build/index.d.ts",
+  "style": "./build/main.css",
+  "sideEffects": [
+    "*.css"
+  ],
+  "files": [
+    "build"
+  ],
+  "repository": {
+    "type": "git",
+    "fullname": "transferwise/dynamic-flow",
+    "url": "git+https://github.com/transferwise/dynamic-flow.git"
+  },
+  "scripts": {
+    "dev": "storybook dev -p 3005",
+    "build": "npm-run-all build:*",
+    "build:ts": "tsc --build ./tsconfig.build.json",
+    "build:css": "postcss src/main.css -o build/main.css",
+    "test": "pnpm test:once",
+    "test:once": "jest --config jest.config.js --env=jsdom",
+    "test:coverage": "jest --config jest.config.js --env=jsdom --coverage",
+    "test:watch": "pnpm test:once --watch",
+    "lint": "npm-run-all lint:ts lint:css",
+    "lint:ts": "eslint 'src/**/*.{js,jsx,ts,tsx}' --quiet",
+    "lint:css": "stylelint --allow-empty-input './src/**/*.css'",
+    "build-storybook": "storybook build -c .storybook"
+  },
+  "devDependencies": {
+    "@babel/core": "7.20.12",
+    "@babel/plugin-syntax-flow": "7.18.6",
+    "@babel/plugin-transform-react-jsx": "7.21.0",
+    "@babel/preset-env": "7.20.2",
+    "@babel/preset-react": "7.18.6",
+    "@babel/preset-typescript": "7.21.0",
+    "@formatjs/cli": "^4.8.3",
+    "@storybook/addon-a11y": "7.0.9",
+    "@storybook/addon-actions": "7.0.9",
+    "@storybook/addon-essentials": "7.0.9",
+    "@storybook/addon-interactions": "7.0.9",
+    "@storybook/addon-links": "7.0.9",
+    "@storybook/react": "7.0.9",
+    "@storybook/react-webpack5": "7.0.9",
+    "@storybook/testing-library": "0.1.0",
+    "@testing-library/dom": "9.2.0",
+    "@testing-library/jest-dom": "5.16.5",
+    "@testing-library/react": "14.0.0",
+    "@testing-library/react-hooks": "8.0.1",
+    "@testing-library/user-event": "13.2.1",
+    "@transferwise/components": "43.13.49",
+    "@transferwise/eslint-config": "8.0.1",
+    "@transferwise/formatting": "^2.10.0",
+    "@transferwise/icons": "3.2.3",
+    "@transferwise/neptune-css": "14.3.45",
+    "@transferwise/neptune-tokens": "8.4.0",
+    "@types/jest": "29.4.0",
+    "@types/react": "18",
+    "@types/react-dom": "18",
+    "@types/testing-library__jest-dom": "5.9.5",
+    "@wise/art": "2.0.1",
+    "@wise/components-theming": "^0.7.4",
+    "babel-jest": "29.5.0",
+    "currency-flags": "4.0.7",
+    "eslint": "8.36.0",
+    "eslint-plugin-storybook": "0.6.12",
+    "jest": "29.5.0",
+    "jest-environment-jsdom": "29.5.0",
+    "jest-fetch-mock": "^3.0.3",
+    "jest-watch-typeahead": "^2.2.2",
+    "npm-run-all": "4.1.5",
+    "postcss": "^8.4.21",
+    "postcss-cli": "^10.1.0",
+    "postcss-import": "^15.1.0",
+    "prettier": "2.8.4",
+    "react": "18.2.0",
+    "react-dom": "18.2.0",
+    "react-intl": "6.2.1",
+    "storybook": "7.0.9",
+    "stylelint": "14.16.1",
+    "stylelint-config-standard": "25.0.0",
+    "stylelint-no-unsupported-browser-features": "5.0.4",
+    "stylelint-value-no-unknown-custom-properties": "4.0.0",
+    "typescript": "4.9.5",
+    "webpack": "5.76.0"
+  },
+  "peerDependencies": {
+    "react": "^18",
+    "react-dom": "^18",
+    "react-intl": "^6"
+  },
+  "dependencies": {
+    "@wise/dynamic-flow-client": "^0.2.0"
+  },
+  "prettier": "@transferwise/eslint-config/.prettierrc.js"
+}