@monkvision/common 4.0.3 → 4.0.4

package/README/APP_UTILS.md

@@ -0,0 +1,52 @@
+# Application Utils
+This README page is aimed at providing documentation on a specific part of the `@monkvision/common` package : the
+application utilities. You can refer to [this page](README.md) for more general information on the package.
+
+This package exports various utilities shared accross the different web and native applications integrating the Monk
+workflow using the MonkJs SDK.
+
+# Monk Application State
+Most of the time, applications integrating the Monk SDK will need the same basic parameters to function :
+- An authentication token to make API requests
+- An inspection ID to know which inspection it should capture or visualize the reports of
+- A vehicle type to know which sights or car 360 wireframes to use in the capture screen or in the inspection report
+- A steering wheel position for the vehicles (left or right)
+- A preferred language to use instead of the default English
+
+This package export some utilities that can be used to more easily handle the state management and the initial values of
+these app parameters.
+
+## MonkAppStateProvider component
+The `MonkAppStateProvider` component is a React context provider that declares the application parameters described
+above. It declares a `MonkAppStateContext` that contains the current authentication token, inspection ID and vehicle
+type and setters functions to update them. Using some configuration props, this context provider also initializes the
+parameters with values that can be fetched from the URL search parameters or the local storage :
+
+- If the `fetchFromSearchParams` prop in the app config is set to `true`, during the first render of the component, it
+  will look in the URL for search parameters described in the `MonkSearchParams` enum in order to update the app params
+  accordingly.
+  - Auth tokens need be compressed using ZLib (ex: using the `zlibCompress` utility function available in this
+    package) and properly URL-encoded before being passed as a URL param. No Monk app should ever use auth tokens
+    obtained from URL search params without compression and encoding.
+  - The token fetched from the search params will always be used in priority over the one fetched from the local
+    storage.
+- During the first render of the MonkAppStateProvider component, it will look in the local storage for a valid
+  authentication token to use.
+  - The storage key used to read / write the auth token in the local storage is the same throughout the Monk SDK and
+    is defined in the `STORAGE_KEY_AUTH_TOKEN` variable exported by this package.
+  - If `fetchFromSearchParams` is also set to `true`, the token fetched from the search params will always be
+    used in priority over the one fetched from the local storage.
+
+| Prop             | Type             | Description                                                                                                                         | Required | Default Value |
+|------------------|------------------|-------------------------------------------------------------------------------------------------------------------------------------|----------|---------------|
+| config           | CaptureAppConfig | The current configuration of the application.                                                                                       | ✔️       |               |
+| onFetchAuthToken | () => void       | Callback called when an authentication token has successfully been fetched from either the local storage, or the URL search params. |          |               |
+| onFetchLanguage  | () => void       | Callback called when the language of the app must be updated because it has been specified in the URL params.                       |          |               |
+
+## useMonkAppState hook
+This hook simply returns the current value of the `MonkAppStateContext` declared by the `MonkAppStateProvider`component.
+It means that it can only be called within the render function of a child of this component. This hook accepts an
+optional parameter called `requireInspection` which specifies if the `authToken` and the `inspectionId` params are
+required. If they are, this hook will guarantee that the return values for these params is not null (even in TypeScript
+typings), but will throw an error if they are.
+

package/README/HOOKS.md

@@ -0,0 +1,242 @@
+# Hooks
+This README page is aimed at providing documentation on a specific part of the `@monkvision/common` package : the
+React hooks. You can refer to [this page](README.md) for more general information on the package.
+
+This package exports various custom hooks used throughout the MonkJs SDK.
+
+### useAsyncEffect
+```tsx
+import { useAsyncEffect } from '@monkvision/common';
+
+function TestComponent() {
+  useAsyncEffect(
+    async () => {
+      const result = myCustomAsyncFunc();
+      return result.value;
+    },
+    [exampleDependency],
+    {
+      onResolve: (value) => {
+        console.log(value);
+      },
+      onReject: (err) => {
+        console.error(err);
+      },
+      onComplete: () => {
+        console.log('Done.');
+      }
+    },
+  );
+}
+```
+Custom hook that can be used to run asyncrhonous effects. It is similar to `useEffect` but makes sure to not execute the
+effect handlers if the effect's Promise resolves after the current component as been dismounted.
+
+### useAsyncInterval
+```tsx
+import { useAsyncInterval } from '@monkvision/common';
+
+function TestComponent() {
+  useAsyncInterval(
+    myCustomAsyncCallback,
+    1000,
+    {
+      onResolve: (value) => {
+        console.log(value);
+      },
+      onReject: (err) => {
+        console.error(err);
+      },
+      onComplete: () => {
+        console.log('Done.');
+      }
+    },
+  );
+}
+```
+This custom hook creates an interval that calls the provided async callback every `delay` milliseconds if the previous
+call isn't still running. If `delay` is `null` or less than 0, the callback will not be called. The promise handlers
+provided will only be called while the component is still mounted.
+
+### useInteractiveStatus
+```tsx
+import { useInteractiveStatus } from '@monkvision/common';
+
+function TestComponent() {
+  const { status, events } = useInteractiveStatus();
+  useEffect(() => console.log('Button status :', status), [status]);
+
+  return <button {...events}>My Button</button>;
+}
+```
+This hook allows the tracking of the interactive status (hovered, active, disabled...) of a React element. It returns
+the interactive status of the element, as well as a set of MouseEvent listeners used to update the status accordingly.
+
+### useInterval
+```tsx
+import { useInterval } from '@monkvision/common';
+
+function TestComponent() {
+  useInterval(() => console.log('Hello World!'), 1000);
+}
+```
+This custom hook creates an interval that calls the provided callback every `delay` milliseconds. If `delay` is `null`
+or less than 0, the callback will not be called.
+
+### useLangProp
+```tsx
+import { useLangProp } from '@monkvision/common';
+
+function TestComponent(props: { lang?: string }) {
+  useLangProp(lang);
+}
+```
+Custom hook used internally by the Monk SDK components to handle the `lang` prop tha tcan be passed to them to manage
+the current language displayed by the component.
+
+### useLoadingState
+```tsx
+import { useEffect } from 'react';
+import { useLoadingState } from '@monkvision/common';
+
+function useCustomApiCall() {
+  const loading = useLoadingState();
+  useEffect(() => {
+    loading.start();
+    myApiCall().then(() => loading.onSuccess()).catch((err) => loading.onError(err));
+  }, []);
+}
+```
+Custom hook used to create a `LoadingState` object. This object can be used to track the processing of a task in the
+component. For instance, you can use this hook to handle the loading and errors of API calls in your components.
+
+### useObjectMemo
+```tsx
+import { useMemo } from 'React';
+import { useObjectMemo } from '@monkvision/common';
+
+function TestComponent() {
+  // These 2 lines are equivalent
+  const foo = useMemo(() => ({ bar, baz }), [bar, baz]);
+  const foo = useObjectMemo({ bar, baz });
+}
+```
+This custom hook is used to have a more handy way of memoizing a record of values.
+
+### useObjectTranslation
+```tsx
+import { useObjectTranslation } from '@monkvision/common';
+
+const translationObject = { en: 'Hello', fr: 'Salut', de: 'Hallo' };
+
+function TestComponent() {
+  const { tObj } = useObjectTranslation();
+  return <div>{tObj(translationObject)}</div>;
+}
+```
+Custom hook used to get a translation function tObj that translates TranslationObjects.
+
+### usePreventExit
+```ts
+import { usePreventExit } from '@monkvision/common';
+
+function MyComponent() {
+  const { allowRedirect } = usePreventExit(true);
+
+  const anyEvent = useCallback(() => {
+    allowRedirect();
+    /** ... */
+  }, [allowRedirect])
+}
+```
+
+This hook is used to prevent the user from leaving the page by displaying a confirmation dialog when the user tries to
+leave the page.
+
+### useQueue
+```tsx
+import { useQueue } from '@monkvision/common';
+
+function TestComponent() {
+  const queue = useQueue<string>((item) => {
+    console.log(item);
+    return Promise.resolve();
+  });
+  ...
+}
+```
+
+This hook is used to create a processing queue. The `process` function passed as a parameter is an async function
+that is used to process items in the queue. You can find more details on how the queue works by taking a look at the
+TSDoc of the `Queue` interface.
+
+### useResponsiveStyle
+```tsx
+import { useResponsiveStyle } from '@monkvision/common';
+import { Styles } from '@monkvision/types';
+
+const styles: Styles = {
+  div: {
+    width: 100,
+    height: 100,
+  },
+  divMobile: {
+    __media: { maxWidth: 500 },
+    backgroundColor: '#ff0000',
+  },
+};
+
+function TestComponent() {
+  const { responsive } = useResponsiveStyle();
+  return <div style={{...styles.div, ...responsive(styles.divMobile)}}>Hello</div>
+}
+```
+This hook returns takes a `ResponsiveStyleProperties` declarations object (see the definition of this type in the
+`@monkvision/types` package for more details) containing a media query and returns either the CSSProperties contained in
+the type, or `null` if the query conditions are not met. Note that if there are no query, the style will be applied.
+
+### useSearchParams
+```tsx
+import { sights } from '@monkvision/sights';
+import { useSearchParams } from '@monkvision/common';
+
+function TestComponent() {
+  const searchParams = useSearchParams();
+  console.log(searchParams.get('myParam'));
+}
+```
+Custom hook used to fetch search params from the current window URL.
+
+### useSightLabel
+```tsx
+import { sights } from '@monkvision/sights';
+import { useSightLabel } from '@monkvision/common';
+
+function TestComponent() {
+  const { label } = useSightLabel();
+  return <div>{label(sights['fesc20-0mJeXBDf'])}</div>;
+}
+```
+Custom hook used to get the label of a sight with the currently selected language.
+
+### useThumbnail
+```tsx
+import { useThumbnail } from '@monkvision/common';
+
+function TestComponent() {
+  const { getThumbnailUrl } = useThumbnail(thumbnailDomain);
+  console.log(getThumbnailUrl(image));
+}
+```
+Custom hook used to generates a thumbnail URL from a full resolution picture.
+
+### useWindowDimensions
+```tsx
+import { useWindowDimensions } from '@monkvision/common';
+
+function TestComponent() {
+  const { width, height, isPortrait } = useWindowDimensions();
+}
+```
+This hook returns the current window dimensions in pixels, and a boolean indicating if the window is in portrait mode
+(width < height) or not.

package/README/INTERNATIONALIZATION.md

@@ -0,0 +1,89 @@
+# Internationalization
+This README page is aimed at providing documentation on a specific part of the `@monkvision/common` package : the
+internationalization. You can refer to [this page](README.md) for more general information on the package.
+
+This package exports utility functions and hooks tools that help you manage the internationalization support of the Monk
+SDK, as well as common translations that can be useful when interacting with the SDK.
+
+# react-i18next
+The internationalization in the Monk SDK (and in Monk Webapps) is handled using [i18n](https://www.i18next.com/) and
+[react-i18next](https://react.i18next.com/). This means that installing some of our packages (like
+`@monkvision/inspection-report-web` for instance) will mean automatically adding these packages as dependencies in your
+lockfile.
+
+We tend to stay as minimal-dependency as we can when developing our SDK, but we felt like i18n and react-i18next were
+packages common enough that it was not worth going through implementing an abstraction package like we did for
+@monkvision/sentry.
+
+Keep in mind : if you do not want internationalization support in your application, you can still use our SDK and
+specify to it which language you want it to use. The following languages are supported by the Monk SDK :
+
+- English (default)
+- French
+- German
+- Dutch
+
+# i18n Utilities
+## useI18nSync hook
+### Description
+This hook is used mostly by MonkJs packages internally to synchronize their own i18n instance with the language param
+or prop that they are provided.
+
+### Example of usage
+
+```typescript
+import i18n from 'i18next';
+import { useI18nSync } from '@monkvision/common';
+
+interface MyComponentProps {
+  lang?: string | null;
+}
+
+function MyComponent(props: MyComponentProps) {
+  useI18nSync(props.lang);
+  ...
+}
+```
+
+## getLanguage
+```ts
+import i18n from 'i18next';
+import { getLanguage } from '@monkvision/common';
+
+console.log(getLanguage(i18n.language));
+```
+This function retrieves the language prefix from a given language string.
+If the prefix is not found in the list of supported languages (monkLanguages in Types package), it returns 'en' as default.
+
+# Common Translations
+## Car Parts
+You can import the car parts translations like this :
+
+```typescript
+import { cartPartLabels } from '@monkvision/common';
+```
+
+The `cartPartLabels` object maps each `VehiclePart` name (enum from `@monkvision/types`) to a `TranslationObject`
+containing a label for each supported language.
+
+## Image Status Labels
+You can import the image status labels translations like this :
+
+```typescript
+import { imageStatusLabels } from '@monkvision/common';
+```
+
+The `imageStatusLabels` object maps each `ImageStatus` (enum from `@monkvision/types`) to an object containing a `title`
+and a `description` property, both of which are TranslationObject`s containing a label for each supported language.
+
+
+## Compliance Issue Labels
+You can import the compliance issue labels translations like this :
+
+```typescript
+import { complianceIssueLabels } from '@monkvision/common';
+```
+
+The `complianceIssueLabels` object maps each `ComplianceIssue` (enum from `@monkvision/types`) to an object containing a
+`title` and a `description` property, both of which are TranslationObject`s containing a label for each supporte
+language.

package/README/STATE_MANAGEMENT.md

@@ -0,0 +1,125 @@
+# State Management
+This README page is aimed at providing documentation on a specific part of the `@monkvision/common` package : the state
+management. You can refer to [this page](README.md) for more general information on the package.
+
+This package exports tools that help you manage the state of MonkJs applications. In Monk projects, the state of an
+inspection and everything that goes with it is represented by a set of different entities. The complete list of entities
+available in what we call the "Monk State" is available in the @monkvision/types package.
+
+The "Monk State" (described in this package by the `MonkState` interface) is simply the list of all entities currently
+stored in the state of your application. This package exports tools that help you initialize, access and update the
+Monk state.
+
+## MonkProvider component
+This package exports a component called `MonkProvider` which is a context provider that will let you access and use the
+Monk state in your application. We recommend placing this provider at the top of your application :
+
+```tsx
+import { MonkProvider } from '@monkvision/common';
+
+function RootComponent() {
+  return (
+    <MonkProvider>
+      ...
+    </MonkProvider>
+  )
+}
+```
+
+After placing this provider in your code, the Monk state will be accessible using the `useMonkState` hook described
+below. This provider will initialize the Monk state with empty values (no entities) by default, but you can pass an
+optional `initialState` prop to the provider to initialize the satte with custom values.
+
+> Important note : If the Monk state context has already been defined previously, this Monk provider component will
+> have no effect. This is because packages of the MonkJs project use this provider internally to set up the state, even
+> if you do not use it in your app.
+
+# useMonkState hook
+Once you have initialized the Monk state in your app using the `MonkProvider` component, you can access the state using
+the `useMonkState` hook as follows :
+
+```tsx
+import { useMonkState } from '@monkvision/common';
+
+function MyComponent() {
+  const { state, dispatch } = useMonkState();
+  ...
+}
+```
+
+This hook behaves similarly to the `useReducer` React hook, and will return two values :
+- `state` : The Monk state object, that updates automatically when an action is dispatched
+- `dispatch` : A dispatch function that will let you dispatch `MonkAction` objects to update the state
+
+The list of actions that can be dispatched is described in the *Monk state actions* section below.
+
+> Important note : This hook will throw an error if called in a component where the MonkContext has not been initialized
+> previously by a MonkProvider
+
+# Monk state actions
+This section enumerates the available actions that can be dispatched in the MonkState.
+
+## ResetState Action
+This action can be dispatched in order to completely reset the MonkState and clear all stored entities. This action does
+not need any payload.
+
+```typescript
+import { MonkResetStateAction, MonkActionType } from '@monkvision/common';
+
+const action: MonkResetStateAction = {
+  type: MonkActionType.RESET_STATE,
+}
+```
+
+## GotOneInspection Action
+This action can be dispatched when details about an inspection have been fetched from the API. The payload of this
+action is actually a partial MonkState containing details about every entity fetched with this inspection.
+
+```typescript
+import { MonkResetStateAction, MonkActionType } from '@monkvision/common';
+
+const action: Monk = {
+  type: MonkActionType.GOT_ONE_INSPECTION,
+  payload: {
+    inspections: [...],
+    images: [...],
+    ...
+  }
+}
+```
+
+## CreatedOneImage Action
+This action can be dispatched after an image has beencreated and uploaded to the API. The payload of this action should
+contain the details about the image that has been created, as well as the ID of the inspection. You can also start by
+creating a local image (with a custom local ID), and then update this image when the API has returned the actual ID of
+the image. To do so, re-dispatch another time the same action, but with the new Id and the property `localId` in the
+payload containing the previous ID assigned to the image when it was created locally.
+
+```typescript
+import { MonkResetStateAction, MonkActionType } from '@monkvision/common';
+
+const action: Monk = {
+  type: MonkActionType.CREATED_ONE_IMAGE,
+  payload: {
+    inspectionId: 'e1cb2852-77f3-4fb5-a851-e700cf31a7d1',
+    image: {...},
+  }
+}
+```
+
+## UpdatedManyTasks Action
+This action can be dispatched after one or multiple tasks' statuses have been updated. The payload of this action should
+be an array containing the details of the tasks that have been updated.
+
+```typescript
+import { MonkResetStateAction, MonkActionType } from '@monkvision/common';
+import { ProgressStatus } from '@monkvision/types';
+
+const action: Monk = {
+  type: MonkActionType.CREATED_ONE_IMAGE,
+  payload: [
+    { id: '2b2ac131-c613-41a9-ac04-d00b942e2290', status: ProgressStatus.IN_PROGRESS },
+    { id: '4097bc0e-02d0-4ed8-9411-b18f0cb922f2', status: ProgressStatus.IN_PROGRESS },
+  ]
+}
+```

package/README/THEMING.md

@@ -0,0 +1,70 @@
+# Theming
+This README page is aimed at providing documentation on a specific part of the `@monkvision/common` package : the
+theme customization. You can refer to [this page](README.md) for more general information on the package.
+
+This package exports tools that help you customize the look and feel of MonkJs applications.
+
+# MonkThemeProvider component
+This package exports a component called `MonkThemeProvider` which is a context provider that will let you specify the
+theme you want to apply to the Monk SDK. In order for this to work, you need to place this component above any Monk SDK
+component :
+
+```tsx
+import { MonkThemeProvider } from '@monkvision/common';
+import { InspectionCapture } from '@monkvision/inspection-capture-web';
+
+function AppComponent() {
+  return (
+    <MonkThemeProvider palette={...}>
+      <InspectionCapture />
+    </MonkThemeProvider>
+  )
+}
+```
+
+This component accepts the following props :
+
+| Prop    | Type                 | Description                         | Required | Default Value        |
+|---------|----------------------|-------------------------------------|----------|----------------------|
+| palette | Partial<MonkPalette> | The colors to used by the Monk SDK. |          | `MonkDefaultPalette` |
+
+# useMonkTheme hook
+Inside a `MonkThemeProvider` child component, you can use the `useMonkTheme` hook to access the current Monk theme. If
+this hook is called while the `MonkThemeProvider` has not been defined, the default Monk theme will be returned. This
+hook will return the following values :
+
+- A `palette` object containing the current color palette
+- A `utils` object containing various utility functions
+
+```tsx
+import { useMonkTheme } from '@monkvision/common';
+
+function MyComponent() {
+  const { palette, utils } = useMonkTheme();
+}
+```
+
+# Utility functions
+The `utils` property of the Monk theme contains the following utility functions :
+
+## getColor
+```typescript
+const { utils } = useMonkTheme();
+const colorValue = utils.getColor(colorProp);
+```
+
+This function takes a `ColorProp` as an argument and returns the corresponding color value based on the current theme.
+`ColorProp` corresponds to the type of the props that you can give to Monk UI components in order to specify a color to
+them. It can either be directly a CSS color value (hexcode, rgba function as a string, etc.), or the name of the color
+in the palette (for instance `primary-dark`).
+
+The `getColor` function will check if the given argument is a color name, and if it is, it will return its correponding
+value in the curerntly used color palette. If the argument given is not a color name, it will be considered as a CSS
+color property and will be return as is.
+
+# Available Theme Customization
+## Color Palette
+You can use the `palette` prop in the MonkThemeProvider to customize the colors of the Monk SDK. The list of available
+colors is defined in the `MonkPalette` interface of the `@monkvision/types` package. The palette given to the provider
+can be a partial palette, where not all colors are implemented. In this case, every missing color will be filled with
+the color present in the default Monk palette.