@smileid/web-components 11.0.0 → 11.0.1

package/README.md

@@ -1,15 +1,15 @@
-# Instructions
-
-These components can be used to capture id document or liveness images
-
-1. [`smart-camera-web`](./components/smart-camera-web/src/)
-2. [`document-capture-screens`](./components/document/src/README.md)
-3. [`selfie-capture-screens`](./components/selfie/README.md)
-
-## Orchestration
-
-To build your own flow, we have several components that can be used together.
-
-### document-capture-instructions
-
-This is the screen used to instruct the user how to capture document using both the camera and/or upload.
+# Instructions
+
+These components can be used to capture id document or liveness images
+
+1. [`smart-camera-web`](./components/smart-camera-web/src/)
+2. [`document-capture-screens`](./components/document/src/README.md)
+3. [`selfie-capture-screens`](./components/selfie/README.md)
+
+## Orchestration
+
+To build your own flow, we have several components that can be used together.
+
+### document-capture-instructions
+
+This is the screen used to instruct the user how to capture document using both the camera and/or upload.

package/dist/README.md

@@ -0,0 +1,15 @@
+# Instructions
+
+These components can be used to capture id document or liveness images
+
+1. [`smart-camera-web`](./components/smart-camera-web/src/)
+2. [`document-capture-screens`](./components/document/src/README.md)
+3. [`selfie-capture-screens`](./components/selfie/README.md)
+
+## Orchestration
+
+To build your own flow, we have several components that can be used together
+
+### document-capture-instructions
+
+This is the screen used to instruct the user how to capture document using both the camera and/or upload.

package/dist/components/README.md

@@ -0,0 +1,14 @@
+# Instructions
+
+These components can be used to capture id document or liveness images
+
+1. [`document-capture-screens`](./document/src/README.md)
+2. [`selfie-capture-screens`](./selfie/README.md)
+
+## Orchestration
+
+To build your own flow, we have several components that can be used together
+
+### document-capture-instructions
+
+This is the screen used to instruct the user how to capture document using both the camera and/or upload.

package/dist/components/document/src/README.md

@@ -0,0 +1,111 @@
+# DocumentCapture Web Component
+
+## Overview
+
+The `DocumentCaptureScreens` is a bespoke web component designed for capturing document images using a camera. It leverages the `SmartCamera` module for camera interaction and permission management.
+This component contains the flow for capturing both front and the back of id documents.
+
+### Importing the Component
+
+To utilize the `DocumentCaptureScreens` component within your project, import it into your JavaScript file as follows:
+
+```js
+import '@smileid/components/document-capture';
+```
+
+### Using the Component
+
+The DocumentCapture component can be embedded in your HTML similarly to any standard HTML element:
+
+```html
+<document-capture-screens></document-capture-screens>
+```
+
+### Attributes
+
+Customize the component's behavior with the following attributes:
+
+#### `hide-instructions`
+
+Omits the capture instructions. This attribute is boolean and does not require a value.
+
+```html
+<document-capture-screens hide-instructions></document-capture-screens>
+```
+
+#### `hide-back-of-id`
+
+Excludes the option to capture the ID's back side. This attribute is boolean.
+
+```html
+<document-capture-screens hide-back-of-id></document-capture-screens>
+```
+
+#### `show-navigation`
+
+Displays navigation controls for the capture process. This attribute is boolean.
+
+```html
+<document-capture-screens show-navigation></document-capture-screens>
+```
+
+#### `document-capture-modes`
+
+Specifies the capture modes, accepting `camera`, `upload`, or both. Value required.
+
+```html
+<document-capture-screens
+  document-capture-modes="camera,upload"
+></document-capture-screens>
+```
+
+### Permissions
+
+Camera permissions are essential for functionality. The component requests permissions automatically. Upon granting, `data-camera-ready` is set to true, and `data-camera-error` is removed. Denied permissions result in `data-camera-error` being set with an error message.
+
+For manual permission handling, appropriately set `data-camera-ready` and `data-camera-error`.
+
+### Error Handling
+
+Errors during permission requests or document capture are managed by the component, setting `data-camera-error` with the respective error message.
+
+### Event Handlers
+
+Capture events emit `document-capture-screens.publish`, providing captured images and metadata:
+
+```json
+{
+  "detail": {
+    "images": [{ "image": "base64-encoded image", "image_type_id": "" }],
+    "meta": {
+      "version": "library version"
+    }
+  }
+}
+```
+
+To handle this event:
+
+```js
+document
+  .querySelector('document-capture-screens')
+  .addEventListener('document-capture-screens.publish', function (event) {
+    console.log(event.detail);
+  });
+```
+
+### Dependencies
+
+`DocumentCaptureScreens` relies on the following modules:
+
+- [document-capture-instructions](./document-capture-instructions/README.md)
+- [document-capture](./document-capture/README.md)
+- [document-capture-review](./document-capture-review/README.md)
+- [SmartCamera](../../../domain/camera/src/README.md)
+- [FileUpload](../../../domain/file-upload/README.md)
+
+These dependencies are automatically imported with the component.
+
+### Compatibility
+
+Designed for modern browsers supporting custom web components, with specific enhancements for multi-camera Samsung devices to prevent blurry image edges. Report compatibility issues with other devices to our support team.

package/dist/components/document/src/document-capture/README.md

@@ -0,0 +1,90 @@
+# IdCapture Web Component
+
+## Overview
+
+The `IdCapture` is a custom web component designed to capture documents using a camera. It uses the `SmartCamera` module to interact with the device's camera and handle permissions.
+
+### Importing the Component
+
+To use the IdCapture component, you need to import it into your JavaScript file:
+
+```js
+import '@smileid/components/document-capture';
+```
+
+### Using the Component
+
+You can use the IdCapture component in your HTML like any other HTML element:
+
+```html
+<document-capture></document-capture>
+```
+
+### IdCapture Web Component Attributes
+
+You can use a mixture of the following attributes to configure the behavior of the component.
+
+#### hide-back-of-id
+
+This attribute, when present, hides the option to capture the back of the ID. It does not require a value.
+
+Usage:
+
+```html
+<document-capture hide-back-of-id></document-capture>
+```
+
+#### show-navigation
+
+This attribute, when present, shows the navigation controls for the document capture process. It does not require a value.
+
+Usage:
+
+```html
+<document-capture show-navigation></document-capture>
+```
+
+### Permissions
+
+The `IdCapture` component requires camera permissions to function. It will automatically request these permissions when used. If the permissions are granted, it will remove the `data-camera-error` attribute from the capture screen and set the `data-camera-ready` attribute to true. If the permissions are denied, it will remove the `data-camera-ready` attribute and set the `data-camera-error` attribute with the error message.
+
+If you handle the permissions yourself, make sure to set `data-camera-ready` and `data-camera-error` appropriately.
+
+### Error Handling
+
+If there is an error while requesting permissions or capturing the document, the `IdCapture` component will handle it and set the `data-camera-error` attribute with the error message.
+
+### Event Handlers
+
+To receive the images after they have been captured, you can listen to the custom event `document-capture.publish`. The data posted to this event has the structure:
+
+```json
+{
+  "detail": {
+    "image": "base64 image",
+    "previewImage": "base64 image"
+  }
+}
+```
+
+Usage:
+
+```js
+document
+  .querySelector('document-capture')
+  .addEventListener('document-capture.publish', function (event) {
+    console.log(event.detail);
+  });
+```
+
+### Dependencies
+
+The `DocumentCapture` component depends on the following module:
+
+- [SmartCamera](../../../../domain/camera/src/README.md)
+
+This module is imported when you use the `DocumentCapture` component in your projects.
+
+### Compatibility
+
+The IdCapture component is designed to work on all modern browsers that support custom web components. However, it includes a special case for multi-camera Samsung devices to mitigate blurry images at the edges. Please report any issues found on other devices to our support team.

package/dist/components/document/src/document-capture-instructions/README.md

@@ -0,0 +1,56 @@
+# Document Instruction Web Component Guide
+
+## Importing the Component
+
+To incorporate the DocumentInstruction component into your project, import it into your JavaScript file as follows:
+
+```js
+import '@smileid/document-capture/document-capture-instructions';
+```
+
+## Using the Component
+
+The `DocumentInstruction` component is designed to provide users with guidance for capturing document images. It can be integrated into your web page as a custom HTML element:
+
+```html
+<document-capture-instructions></document-capture-instructions>
+```
+
+### Customizing the Component
+
+Adjust the component's behavior and appearance using the following attributes:
+
+#### `show-navigation`
+
+Displays navigation controls, facilitating user interaction during the document capture process. This attribute is boolean and does not require a value.
+
+```html
+<document-capture-instructions show-navigation></document-capture-instructions>
+```
+
+#### `document-capture-modes`
+
+Determines the available modes for document capture. This attribute accepts a comma-separated string specifying the modes:
+
+- `camera`: Enables capturing document images using the camera.
+- `upload`: Allows uploading document images from the device.
+- `camera,upload`: Offers users a choice between capturing images using the camera or uploading from the device.
+
+```html
+<document-capture-instructions
+  document-capture-modes="camera,upload"
+></document-capture-instructions>
+```
+
+## Example
+
+Here is a complete example demonstrating how to embed the `DocumentInstruction` component with navigation controls and both capture modes enabled:
+
+```html
+<document-capture-instructions
+  show-navigation
+  document-capture-modes="camera,upload"
+></document-capture-instructions>
+```
+
+This setup provides an intuitive interface for users, enabling them to receive instructions, navigate through the capture process, and choose their preferred method of document image submission.

package/dist/components/document/src/document-capture-review/README.md

@@ -0,0 +1,79 @@
+# DocumentCaptureReview Web Component
+
+The `DocumentCaptureReview` component is designed to facilitate user interaction by allowing them to review and verify the accuracy of captured images. Users have the option to accept the captured image or initiate a recapture if necessary.
+
+## Usage
+
+To integrate the `DocumentCaptureReview` component into your web application, insert the custom HTML tag as follows, specifying attributes for the captured image data and optional features like navigation controls:
+
+```html
+<document-capture-review
+  data-image="base64image"
+  show-navigation
+  hide-back-to-host
+></document-capture-review>
+```
+
+### Attributes
+
+- `data-image`: A base64 encoded string of the captured image to be reviewed.
+- `show-navigation`: (Optional) Shows navigation controls for the review process. This attribute is boolean and does not require a value.
+- `hide-back-to-host`: (Optional) Hides the option to return to the host application or page. This attribute is boolean and does not require a value.
+
+## Event Handling
+
+### Image Acceptance
+
+When a user confirms the captured image as acceptable, the `document-capture-review.accepted` event is emitted. Implement an event listener to handle this action:
+
+```js
+document
+  .querySelector('document-capture-review')
+  .addEventListener('document-capture-review.accepted', function (event) {
+    // Handle the image acceptance action here
+  });
+```
+
+### Recapture Request
+
+If the user decides to recapture the image, the `document-capture-review.rejected` event is triggered. Set up an event listener to manage this scenario:
+
+```js
+document
+  .querySelector('document-capture-review')
+  .addEventListener('document-capture-review.rejected', function (event) {
+    // Handle the recapture request here
+  });
+```
+
+## Example
+
+Below is a sample implementation showcasing how to use the `IdReview` component with an event listener for both accepting an image and requesting a recapture:
+
+```html
+<document-capture-review
+  data-image="base64image"
+  show-navigation
+  hide-back-to-host
+></document-capture-review>
+
+<script>
+  const idReviewElement = document.querySelector('document-capture-review');
+
+  idReviewElement.addEventListener(
+    'document-capture-review.accepted',
+    function (event) {
+      console.log('Image accepted by the user.');
+      // Additional logic for accepted image
+    },
+  );
+
+  idReviewElement.addEventListener(
+    'document-capture-review.rejected',
+    function (event) {
+      console.log('User requested to recapture the image.');
+      // Additional logic for image recapture
+    },
+  );
+</script>
+```

package/dist/components/selfie/README.md

@@ -0,0 +1,225 @@
+# SelfieCaptureScreens Web Component
+
+## Overview
+
+The `SelfieCaptureScreens` is a custom web component designed to capture selfies and liveness images using a camera. It uses the `SmartCamera` module to interact with the device's camera and handle permissions.
+
+### Importing the Component
+
+To use the SelfieCaptureScreens component, you need to import it into your JavaScript file:
+
+```js
+import '@smileid/web-components/selfie-capture-screens';
+```
+
+### Using the Component
+
+You can use the SelfieCaptureScreens component in your HTML like any other HTML element:
+
+```html
+<selfie-capture-screens></selfie-capture-screens>
+```
+
+### SelfieCaptureScreens Web Component Attributes
+
+You can use a mixture of the following attributes to configure the behavior of the component.
+
+#### hide-instructions
+
+This attribute, when present, hides the instructions for the liveness capture process. It does not require a value.
+
+Usage:
+
+```html
+<selfie-capture-screens hide-instructions></selfie-capture-screens>
+```
+
+#### show-navigation
+
+This attribute, when present, shows the navigation controls for the liveness capture process. It does not require a value.
+
+Usage:
+
+```html
+<selfie-capture-screens show-navigation></selfie-capture-screens>
+```
+
+### Permissions
+
+The `SelfieCaptureScreens` component requires camera permissions to function. It will automatically request these permissions when used. If the permissions are granted, it will remove the `data-camera-error` attribute from the capture screen and set the `data-camera-ready` attribute to true. If the permissions are denied, it will remove the `data-camera-ready` attribute and set the `data-camera-error` attribute with the error message.
+
+If you handle the permissions yourself, make sure to set `data-camera-ready` and `data-camera-error` appropriately.
+
+### Error Handling
+
+If there is an error while requesting permissions or capturing the images, the `SelfieCaptureScreens` component will handle it and set the `data-camera-error` attribute with the error message.
+
+### Event Handlers
+
+To receive the images after they have been captured, you can listen to the custom event `selfie-capture-screens.publish`. The data posted to this event has the structure:
+
+```json
+{
+  "detail": {
+    "images": [{ "image": "base64 image", "image_type_id": "" }],
+    "meta": {
+      "version": "version of the library in use"
+    }
+  }
+}
+```
+
+Usage:
+
+```js
+document
+  .querySelector('selfie-capture-screens')
+  .addEventListener('selfie-capture-screens.publish', function (event) {
+    console.log(event.detail);
+  });
+```
+
+### Dependencies
+
+The `SelfieCaptureScreens` component depends on the following modules:
+
+- [selfie-capture](#selfiecapture-web-component)
+- [selfie-capture-review](#selfiecapturereview-web-component)
+- [Selfie-instructions](#selfiecaptureinstructions-web-component)
+- [SmartCamera](../../domain/camera/src/README.md)
+
+These modules are imported when you use the `SelfieCaptureScreens` component in your projects.
+
+### SelfieCaptureInstructions Web Component
+
+#### Overview
+
+The `SelfieCaptureInstructions` is a custom web component designed to show an instruction on how to capture a clear selfie image.
+
+#### Importing the SelfieCaptureInstructions Component
+
+To use the SelfieCaptureInstructions component, you need to import it into your JavaScript file:
+
+```js
+import '@smileid/web-components/selfie-capture-instructions';
+```
+
+#### show-navigation
+
+This attribute, when present, shows the navigation controls for the document capture process. It does not require a value.
+
+Usage:
+
+```html
+<selfie-capture-instructions show-navigation></selfie-capture-instructions>
+```
+
+### SelfieCapture Web Component
+
+#### Overview
+
+The `SelfieCapture` is a custom web component designed to capture selfies and liveness images using a camera. It uses the `SmartCamera` module to interact with the device's camera and handle permissions.
+
+#### Importing the SelfieCapture Component
+
+To use the SelfieCapture component, you need to import it into your JavaScript file:
+
+```js
+import '@smileid/web-components/selfie-capture';
+```
+
+### Using the SelfieCapture Component
+
+You can use the SelfieCapture component in your HTML like any other HTML element:
+
+```html
+<selfie-capture></selfie-capture>
+```
+
+### SelfieCapture Web Component Attributes
+
+You can use a mixture of the following attributes to configure the behavior of the component.
+
+#### show-navigation
+
+This attribute, when present, shows the navigation controls for the document capture process. It does not require a value.
+
+Usage:
+
+```html
+<selfie-capture show-navigation></selfie-capture>
+```
+
+### Permissions
+
+The `SelfieCapture` component requires camera permissions to function. It will automatically request these permissions when used. If the permissions are granted, it will remove the `data-camera-error` attribute from the capture screen and set the `data-camera-ready` attribute to true. If the permissions are denied, it will remove the `data-camera-ready` attribute and set the `data-camera-error` attribute with the error message.
+
+If you handle the permissions yourself, make sure to set `data-camera-ready` and `data-camera-error` appropriately.
+
+### Error Handling
+
+If there is an error while requesting permissions or capturing the images, the `SelfieCapture` component will handle it and set the `data-camera-error` attribute with the error message.
+
+### Event Handlers
+
+To receive the images after they have been captured, you can listen to the custom event `selfie-capture.publish`. The data posted to this event has the structure:
+
+```json
+{
+ "detail": {
+  "images": [
+   {"image": "
+
+base64 image", "image_type_id": ""}
+  ],
+  "meta": {
+   "version": "version of the library in use"
+  }
+ }
+}
+```
+
+Usage:
+
+```js
+document
+  .querySelector('selfie-capture')
+  .addEventListener('selfie-capture.publish', function (event) {
+    console.log(event.detail);
+  });
+```
+
+### SelfieCaptureReview Web Component
+
+This component is used to allow the user to verify the accuracy of the capture.
+The user can choose to use the captured image or recapture a new selfie.
+
+Usage:
+
+```html
+<selfie-capture-review
+  data-image="base64 image"
+  show-navigation
+  hide-back-to-host
+></selfie-capture-review>
+```
+
+When a user accepts an image, an event is triggered as shown below:
+
+```js
+document
+  .querySelector('selfie-capture-review')
+  .addEventListener('selfie-capture-review.accepted', function (event) {});
+```
+
+When a user wants to recapture a selfie, an event is triggered as shown below:
+
+```js
+document
+  .querySelector('selfie-capture-review')
+  .addEventListener('selfie-capture-review.rejected', function (event) {});
+```
+
+### Compatibility
+
+The SelfieCaptureScreens component is designed to work on all modern browsers that support custom web components. However, it includes a special case for multi-camera Samsung devices to mitigate blurry images at the edges. Please report any issues found on other devices to our support team.